DOC : major work to development workflow docs

- github PR as primary mode of communication close #2198
matplotlib · tacaswell · Jun 29, 2014 · Jun 29, 2014 · Jun 30, 2014 · Jun 30, 2014
commit 284135ef2866d54ea1bc0d6cbb64d7ff5f2bcdfc
diff --git a/doc/devel/gitwash/branch_list.png b/doc/devel/gitwash/branch_list.png
diff --git a/doc/devel/gitwash/branch_list_compare.png b/doc/devel/gitwash/branch_list_compare.png
diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst
@@ -4,6 +4,18 @@
 Development workflow
 ====================
 
+You've discovered a bug or something else you want to change
+in matplotlib_ .. |emdash| excellent!
+
+You've worked out a way to fix it |emdash| even better!
+
+You want to tell us about it |emdash| best of all!
+
+The easiest way to contribute to matplotlib_ is through github_.  If
+for some reason you don't want to use github, see
+:ref:`making-patches` for instructions on how to email patches to the
+mailing list.
+
 You already have your own forked copy of the matplotlib_ repository, by
 following :ref:`forking`, :ref:`set-up-fork`, and you have configured
 git_ by following :ref:`configure-git`.
@@ -15,8 +27,10 @@ Workflow summary
   to the main matplotlib_ development repo.  Your ``master`` then will follow
   the main matplotlib_ repository.
 * Start a new *feature branch* for each set of edits that you do.
-* If you can avoid it, try not to merge other branches into your feature
-  branch while you are working.
+* Do not merge the ``master`` branch or maintenance tracking branches
+  into your feature branch.  If you need to include commits from upstream
+  branches (either to pick up a bug fix or to resolve a conflict) please
+  *rebase* your branch on the upstream branch.
 * Ask for review!
 
 This way of working really helps to keep work well organized, and in
@@ -103,60 +117,32 @@ In more detail
 #. To push the changes up to your forked repo on github_, do a ``git
    push`` (see `git push`).
 
-Asking for code review
-======================
-
-#. Go to your repo URL |emdash| e.g.,
-   ``http://github.com/your-user-name/matplotlib``.
-#. Click on the *Branch list* button:
-    
-   .. image:: branch_list.png
+Asking for code review |emdash| open a Pull Request (PR)
+========================================================
 
-#. Click on the *Compare* button for your feature branch |emdash| here ``my-new-feature``:
-
-   .. image:: branch_list_compare.png
+It's a good idea to consult the :ref:`pull-request-checklist` to make
+sure your pull request is ready for merging.
 
-#. If asked, select the *base* and *comparison* branch names you want to
-   compare.  Usually these will be ``master`` and ``my-new-feature``
-   (where that is your feature branch name).
-#. At this point you should get a nice summary of the changes.  Copy the
-   URL for this, and post it to the `matplotlib mailing list`_, asking for
-   review.  The URL will look something like:
-   ``http://github.com/your-user-name/matplotlib/compare/master...my-new-feature``.
-   There's an example at
-   http://github.com/matthew-brett/nipy/compare/master...find-install-data
-   See: http://github.com/blog/612-introducing-github-compare-view for
-   more detail.
 
-The generated comparison, is between your feature branch
-``my-new-feature``, and the place in ``master`` from which you branched
-``my-new-feature``.  In other words, you can keep updating ``master``
-without interfering with the output from the comparison.  More detail?
-Note the three dots in the URL above (``master...my-new-feature``) and
-see :ref:`dot2-dot3`.
+#. Go to your repo URL |emdash| e.g.,
+   ``http://github.com/your-user-name/matplotlib``.
 
-It's a good idea to consult the :ref:`pull-request-checklist` to make
-sure your pull request is ready for merging.
+#. Select your feature branch from the drop down menu:
 
-Asking for your changes to be merged into the main repo
-=======================================================
+#. Click on the green button:
 
-When you are ready to ask for the merge of your code:
+#. Make sure that you are requesting a pull against the correct branch
 
-#. Go to the URL of your forked repo, say
-   ``http://github.com/your-user-name/matplotlib.git``.
-#. Click on the 'Pull request' button:
+#. Enter a PR heading and description (if there is only one commit in
+   the PR github will automatically fill these fields for you).  If
+   this PR is addressing a specific issue, please reference it by number
+   (ex #1325) which github will automatically make into links.
 
-   .. image:: pull_button.png
+#. Click 'Create Pull Request' button!
 
-   Enter a message; we suggest you select only ``matplotlib`` as the
-   recipient.  The message will go to the `matplotlib mailing list`_.  Please
-   feel free to add others from the list as you like.
+#. Discussion of the change will take place in the pull request
+   thread.
 
-#. If the branch is to be merged into a maintenance branch on the main
-   repo, make sure the "base branch" indicates the maintenance branch
-   and not master.  Github can not automatically determine the branch
-   to merge into.
 
 Staying up to date with changes in the central repository
 =========================================================

diff --git a/doc/devel/gitwash/forking_hell.rst b/doc/devel/gitwash/forking_hell.rst
@@ -26,7 +26,7 @@ Create your own forked copy of matplotlib_
 
    .. image:: forking_button.png
 
-   Now, after a short pause and some 'Hardcore forking action', you
-   should find yourself at the home page for your own forked copy of matplotlib_.
+   Now, after a short pause you should find yourself at the home page
+   for your own forked copy of matplotlib_.
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/index.rst b/doc/devel/gitwash/index.rst
@@ -11,6 +11,6 @@ Contents:
    git_intro
    git_install
    following_latest
-   patching
    git_development
    git_resources
+   patching
diff --git a/doc/devel/gitwash/patching.rst b/doc/devel/gitwash/patching.rst
@@ -2,19 +2,6 @@
  Making a patch
 ================
 
-You've discovered a bug or something else you want to change
-in matplotlib_ .. |emdash| excellent!
-
-You've worked out a way to fix it |emdash| even better!
-
-You want to tell us about it |emdash| best of all!
-
-The easiest way is to make a *patch* or set of patches.  Here
-we explain how.  Making a patch is the simplest and quickest,
-but if you're going to be doing anything more than simple
-quick things, please consider following the
-:ref:`git-development` model instead.
-
 .. _making-patches:
 
 Making patches
@@ -107,28 +94,4 @@ code, just return to the ``master`` branch::
 
    git checkout master
 
-Moving from patching to development
-===================================
-
-If you find you have done some patches, and you have one or
-more feature branches, you will probably want to switch to
-development mode.  You can do this with the repository you
-have.
-
-Fork the matplotlib_ repository on github_ |emdash| :ref:`forking`.
-Then::
-
-   # checkout and refresh master branch from main repo
-   git checkout master
-   git pull origin master
-   # rename pointer to main repository to 'upstream'
-   git remote rename origin upstream
-   # point your repo to default read / write to your fork on github
-   git remote add origin git@github.com:your-user-name/matplotlib.git
-   # push up any branches you've made and want to keep
-   git push origin the-fix-im-thinking-of
-
-Then you can, if you want, follow the
-:ref:`development-workflow`.
-
 .. include:: links.inc
diff --git a/doc/devel/gitwash/pull_button.png b/doc/devel/gitwash/pull_button.png