add instructions to update branches

docs/development/submitting-patches.rst

@@ -57,6 +57,67 @@ Important information should be documented with prose in the ``docs`` section.
 To ensure it builds and passes `doc8`_ style checks you can run
 ``make docs`` and ``make lint`` respectively.
 
+Keeping your local branch updated
+---------------------------------
+
+As you work, it is helpful to keep your local branch up-to-date with the PRs
+that are merged into the main Warehouse repository. Most people working on
+the project use this workflow.
+
+The following documentation assumes that you have git configured so that when
+you run the following command:
+
+.. code-block:: console
+
+  git remote -v
+
+Your output looks like this:
+
+.. code-block:: console
+
+  origin  https://github.com/USERNAME/warehouse.git (fetch)
+  origin  https://github.com/USERNAME/warehouse.git (push)
+  upstream  https://github.com/pypa/warehouse.git (fetch)
+  upstream  https://github.com/pypa/warehouse.git (push)
+
+
+In the example above, ``USERNAME`` is your username on GitHub.
+
+First, fetch the changes from the ``upstream`` Warehouse repository:
+
+.. code-block:: console
+
+  git fetch upstream
+
+Then, check out your master branch, and rebase the changes on top of it:
+
+.. code-block:: console
+
+  git checkout master
+  git rebase upstream/master
+
+Next, push the changes you have fetched to your ``origin`` branch on GitHub:
+
+.. code-block:: console
+
+  git checkout master
+  git push origin master
+
+Now your local branch and your ``origin`` are up-to-date with the most recent
+changes on the ``upstream`` Warehouse branch.
+
+To keep your feature branches updated, the process is similar:
+
+.. code-block:: console
+
+   git checkout awesome-feature
+   git fetch upstream
+   git rebase upstream/master
+
+Now your feature branch has been updated with the latest changes from the
+``upstream`` Warehouse repository.
+
+
 .. _`Write comments as complete sentences.`: http://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
 .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists
 .. _`Studies have shown`: https://smartbear.com/smartbear/media/pdfs/wp-cc-11-best-practices-of-peer-code-review.pdf