ARROW-14760: [Doc] Steps in making your first PR - PR life cycle

Add **Lifecycle of a Pull Request** section of the new Contributor's guide.

Closes #11837 from AlenkaF/ARROW-14760

Lead-authored-by: Alenka Frim <frim.alenka@gmail.com>
Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com>
Signed-off-by: Nic Crane <thisisnic@gmail.com>

docs/source/developers/contributing.rst

@@ -194,6 +194,8 @@ direct questions, such as:
 
 If you ask these questions and do not get an answer, it is OK to ask again.
 
+.. _pull_request_and_review:
+
 Pull request and review
 +++++++++++++++++++++++
 
@@ -243,6 +245,8 @@ message of that commit, the merge tool adds the pull request description, a
 link back to the pull request, and attribution to the contributor and any
 co-authors.
 
+.. _git_conventions:
+
 Local git conventions
 +++++++++++++++++++++
 

docs/source/developers/guide/step_by_step/pr_and_github.rst

@@ -24,14 +24,202 @@
 
 .. _pr_and_github:
 
-****************************
-Lifecycle of a Pull Request
-****************************
+***************************
+Lifecycle of a pull request
+***************************
 
+:ref:`As mentioned before<set-up>`, the Arrow project uses Git for
+version control and a workflow based on pull requests. That means
+that you contribute the changes to the code by creating a branch
+in Git, make changes to the code, push the changes to your ``origin``
+which is your fork of the Arrow repository on GitHub and then you
+create a **pull request** against the official Arrow repository
+which is saved in your set up as ``upstream``.
 
-Creating a PR 🙀
-================
+You should have Git set up by now, have cloned the repository,
+have successfully built Arrow and have a JIRA issue to work on.
 
+**Before making changes to the code, you should create a new
+branch in Git.**
 
-Reviews and get the PR merge 🎉
-===============================
+1. Update/sync the code from your ``upstream``
+   in the master branch. Run it in the shell from the ``arrow`` directory.
+
+   .. code:: console
+
+      $ git checkout master # select the main Arrow branch
+      $ git fetch upstream # check for changes in upstream/master
+      $ git pull --ff-only upstream master # save the changes from upstream/master
+
+   Note: ``--ff-only`` applies changes only if they can be fast-forwarded
+   without conflicts or creating merge commits.
+
+2. Create a new branch
+
+   .. code:: console
+
+      $ git checkout -b <branch-name>
+
+   or (does the same thing)
+
+   .. code:: console
+
+      $ git switch --create <branch-name>
+
+Now you can make changes to the code. To see the changes
+made in the library use this two commands:
+
+.. code:: console
+
+   $ git status # to see what files are changed
+   $ git diff # to see code change per file
+
+Creating a pull request 
+==========================
+
+Once you are satisfied with the changes, run the :ref:`tests <testing>`
+and linters and then go ahead and commit the changes.
+
+3. Add and commit the changes
+
+   .. code:: console
+         
+      $ git add <filenames>
+      $ git commit -m "<message>"
+
+   Alternatively, you can add and commit in one step, if all the files changed
+   are to be committed (-a to add all, -m for message)
+
+   .. code:: console      
+
+      $ git commit -am "<message>"
+
+4. Then push your work to your Arrow fork
+
+   .. code:: console
+
+      $ git push origin <branch-name>
+
+.. note::
+
+   Your work is now still under your watchful eye so it's not a problem
+   if you see any errors you would like to correct. You can make an
+   additional commit to correct, and Git has lots of ways to
+   amend, delete, revise, etc. See https://git-scm.com/docs for more
+   information.
+
+   Until you make the pull request, nothing is visible on the Arrow
+   repository and you are free to experiment.
+
+If all is set, you can make the pull request!
+
+5. Go to ``https://github.com/<your username>/arrow`` where you will see a box with
+   the name of the branch that you pushed and next to it a green button
+   **Compare & pull request**. After clicking on it, you should add a
+   title and description of the pull request. Underneath you can check
+   once again the changes you have made.
+
+   .. seealso::
+
+      Get more details on naming the pull request in Arrow repository
+      and other additional information :ref:`pull_request_and_review`
+      section.
+
+Reviews and merge of the pull request
+=====================================
+
+When the pull request is submitted it waits to get reviewed. One of
+great things about open source is that your work can get lots of feedback and
+so it gets perfected. Do not be discouraged by the time it takes for
+the PR to get merged due to reviews and corrections. It is a process
+that supports quality and with it you can learn a lot.
+
+If it still takes too long to get merged, do not hesitate to remind
+maintainers in the comment section of the pull request and post
+reminders on the JIRA ticket also.
+
+How to get your pull request to be reviewed?
+--------------------------------------------
+
+Arrow maintainers will be notified when a pull request is created and
+they will get to it as soon as possible. If days pass and it still had
+not been reviewed go ahead and mention the reporter of the JIRA issue 
+or a developer that you communicated with via JIRA comments, mailing
+list or GitHub.
+
+To put a **mention** in GitHub insert @ in the comment and select the
+username from the list.
+
+Commenting on a pull request
+----------------------------
+
+When a pull request is open in the repository you and other developers
+can comment on the proposed solution.
+
+To create a general comment navigate to the **Conversation** tab of
+you pull request and start writing in the comment box at the bottom of
+the page.
+
+You can also comment on a section of the file to point out something
+specific from your code. To do this navigate to **Files changed** tab and
+select a line you want to insert the comment to. Hovering over the beginning
+of the line you will see a **blue plus icon**. You can click on it or drag
+it to select multiple lines and then click the icon to insert the comment.
+
+Resolve conversation
+--------------------
+
+You can resolve a conversion in a pull request review by clicking
+**Resolve conversation** in the **Files changed** tab. This way the
+conversation will be collapsed and marked as resolved which will make it
+easier for you to organize what is done and what still needs to be addressed.
+
+Updating your pull request
+--------------------------
+
+The procedure after getting reviews is similar to creating the initial pull request.
+You need to update your code locally, make a commit, update the branch to sync
+it with upstream and push your code to origin. It will automatically be updated
+in your pull request as well.
+
+The steps for updating the pull request would then be as follows:
+
+1. Updating the code locally and making a commit as before:
+
+   .. code:: console
+
+      $ git commit -am "<message>" #if all changed files are to be committed
+
+2. **Important!** In case there are commits from other developers on the Pull
+   Request branch or if you committed suggestions from the GitHub you need
+   to update you code with ``origin`` before rebasing! To do this run:
+
+   .. code:: console
+
+      $ git pull origin <branch-name>
+
+   Here we merge the new commits with our local branch and we do not rebase.
+
+3. Now we have to update the branch to sync with upstream master Arrow branch.
+   This way the pull request will be able to get merged. We use rebase in this
+   case.
+
+   .. code:: console
+
+      $ git pull upstream master --rebase
+
+4. Now you can push the changes by running:
+
+   .. code:: console
+
+         $ git push origin <branch-name>
+
+.. seealso::
+
+   See more about updating the branch (we use ``rebase``, not ``merge``) in
+   the review process :ref:`here <git_conventions>`. 
+
+If the review process is successful your pull request will get merged.
+
+Congratulations! 🎉
+===================