DOC: Update Development Workflow Page

The "Basic Workflow" section of the Development Workflow page was reorganized
to make it clearer to new users and remove/update old material.

Major changes:

- Moved the core developer notes. Core dev notes are confusing in basic usage
  information. Updated a couple of the commands

- Added more commands and reorgaized the "New Feature Branch" section. Took
  some text from "Rebasing" and moved it here, because it was redundant.

- Made many changes to the "Editing Workflow" to clarify commands. Moved some
  git push stuff into this section as well.

- Moved pull request section to just after editing workflow. Removed outdated
  images and simplified the text. Make code review requirements explicit.

- Moved rebasing and troubleshooting sections to the end. Could add more here
  later.

- Links renamed and broken link removed.

1 files changed, 159 insertions, 193 deletions

diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst
index c67a5e457..6458059cb 100644
--- a/doc/source/dev/gitwash/development_workflow.rst
+++ b/doc/source/dev/gitwash/development_workflow.rst
@@ -16,93 +16,63 @@ Basic workflow
 
 In short:
 
-1. Update your ``master`` branch if it's not up to date.
-   Then start a new *feature branch* for each set of edits that you do.
+1. Start a new *feature branch* for each set of edits that you do.
    See :ref:`below <making-a-new-feature-branch>`.
 
-   Avoid putting new commits in your ``master`` branch.
-
 2. Hack away! See :ref:`below <editing-workflow>`
 
-3. Avoid merging other branches into your feature branch while you are
-   working.
-
-   You can optionally rebase if really needed,
-   see :ref:`below <rebasing-on-master>`.
-
-4. When finished:
+3. When finished:
 
    - *Contributors*: push your feature branch to your own Github repo, and
-     :ref:`ask for code review or make a pull request <asking-for-merging>`.
-
-   - *Core developers* (if you want to push changes without
-     further review)::
-
-         # First, either (i) rebase on upstream -- if you have only few commits
-         git fetch upstream
-         git rebase upstream/master
-
-         # or, (ii) merge to upstream -- if you have many related commits
-         git fetch upstream
-	 git merge --no-ff upstream/master
-
-         # Recheck that what is there is sensible
-         git log --oneline --graph
-         git log -p upstream/master..
-
-         # Finally, push branch to upstream master
-	 git push upstream my-new-feature:master
-
-     See :ref:`below <pushing-to-main>`.
-
-.. note:: It's usually a good idea to use the ``-n`` flag to ``git push``
-          to check first that you're about to push the changes you want to
-          the place you want.
+     :ref:`create a pull request <asking-for-merging>`.
 
+   - *Core developers* If you want to push changes without
+     further review, see the notes :ref:`below <pushing-to-main>`.
+     
 This way of working helps to keep work well organized and the history
 as clear as possible.
 
-.. note::
-
-   Do not use ``git pull`` --- this avoids common mistakes if you are
-   new to Git. Instead, always do ``git fetch`` followed by ``git
-   rebase``, ``git merge --ff-only`` or ``git merge --no-ff``,
-   depending on what you intend.
-
 .. seealso::
 
-   See discussions on `linux git workflow`_,
-   and `ipython git workflow <http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html>`__.
+   There are many online tutorials to help you `learn git`_. For discussions
+   of specific git workflows, see these discussions on `linux git workflow`_,
+   and `ipython git workflow`_.
 
 .. _making-a-new-feature-branch:
 
 Making a new feature branch
 ===========================
 
-To update your master branch, use::
+First, update your master branch with changes that have been made in the main
+Numpy repository. In this case, the ``--ff-only`` flag ensures that a new
+commit is not created when you merge the upstream and master branches. It is
+very important to avoid merging adding new commits to ``master``.
+
+::
 
+   # go to the master branch
+   git checkout master
+   # download changes from github
    git fetch upstream
+   # update the master branch
    git merge upstream/master --ff-only
+   # Push new commits to your Github repo
+   git push
 
-To create a new branch and check it out, use::
-
-   git checkout -b my-new-feature upstream/master
-
-Generally, you will want to keep this branch also on your public github_ fork
-of NumPy_.  To do this, you `git push`_ this new branch up to your github_
-repo.  Generally (if you followed the instructions in these pages, and
-by default), git will have a link to your github_ repo, called
-``origin``.  You push up to your own repo on github_ with::
+.. note::
 
-   git push origin my-new-feature
+   You could also use ``pull``, which combines ``fetch`` and ``merge``, as
+   follows::
+   
+        git pull --ff-only upstream master
 
-In git >= 1.7 you can ensure that the link is correctly set by using the
-``--set-upstream`` option::
+   However, never use ``git pull`` without explicity indicating the source
+   branch (as above); the inherent ambiguity can cause problems. This avoids a
+   common mistake if you are new to Git. 
 
-   git push --set-upstream origin my-new-feature
+Finally create a new branch for your work and check it out::
 
-From now on git_ will know that ``my-new-feature`` is related to the
-``my-new-feature`` branch in your own github_ repo.
+   git checkout -b my-new-feature master
 
 
 .. _editing-workflow:
@@ -116,18 +86,21 @@ Overview
 ::
 
    # hack hack
-   git add my_new_file
-   git commit -am 'ENH: some message'
-
+   git status # Optional
+   git diff # Optional
+   git add modified_file
+   git commit 
    # push the branch to your own Github repo
    git push
 
 In more detail
 --------------
 
-#. Make some changes
-#. See which files have changed with ``git status`` (see `git status`_).
-   You'll see a listing like this one::
+#. Make some changes. When you feel that you've made a complete, working set
+   of related changes, move on to the next steps.
+
+#. Optional: Check which files have changed with ``git status`` (see `git
+   status`_).  You'll see a listing like this one::
 
      # On branch my-new-feature
      # Changed but not updated:
@@ -142,21 +115,60 @@ In more detail
      #	INSTALL
      no changes added to commit (use "git add" and/or "git commit -a")
 
-#. Check what the actual changes are with ``git diff`` (`git diff`_).
-#. Add any new files to version control ``git add new_file_name`` (see
-   `git add`_).
-#. To commit all modified files into the local copy of your repo,, do
-   ``git commit -am 'A commit message'``.  Note the ``-am`` options to
-   ``commit``. The ``m`` flag just signals that you're going to type a
-   message on the command line.   If you leave it out, an editor will open in
-   which you can compose your commit message.  For non-trivial commits this is
-   often the better choice.  The ``a`` flag - you can just take on faith - or
-   see `why the -a flag?`_ - and the helpful use-case description in the
-   `tangled working copy problem`_. The section on
-   :ref:`commit messages <writing-the-commit-message>` below might also be useful.
-#. To push the changes up to your forked repo on github_, do a ``git
-   push`` (see `git push`).
-
+#. Optional: Compare the changes with the previous version using with ``git
+   diff`` (`git diff`_). This brings up a simple text browser interface that
+   highlights the difference between your files and the previous verison.
+
+#. Add any relevant modified or new files using  ``git add modified_file``
+   (see `git add`_). This puts the files into a staging area, which is a queue
+   of files that will be added to your next commit. Only add files that have
+   related, complete changes. Leave files with unfinished changes for later
+   commits.
+
+#. To commit the staged files into the local copy of your repo, do ``git
+   commit``. At this point, a text editor will open up to allow you to write a
+   commit message. Read the :ref:`commit message
+   section<writing-the-commit-message>` to be sure that you are writing a
+   properly formatted and sufficiently detailed commit message. After saving
+   your message and closing the editor, your commit will be saved. For trivial
+   commits, a short commit message can be passed in through the command line
+   using the ``-m`` flag. For example, ``git commit -am "ENH: Some message"``. 
+   
+   In some cases, you will see this form of the commit command: ``git commit
+   -a``. The extra ``-a`` flag automatically commits all modified files and
+   removes all deleted files. This can save you some typing of numerous ``git
+   add`` commands; however, it can add unwanted changes to a commit if you're
+   not careful. For more information, see `why the -a flag?`_ - and the
+   helpful use-case description in the `tangled working copy problem`_.  
+
+#. Push the changes to your forked repo on github_::
+
+      git push origin my-new-feature
+
+   For more information, see `git push`_.
+    
+.. note::
+    
+   Assuming you have followed the instructions in these pages, git will create
+   a default link to your github_ repo called ``origin``.  In git >= 1.7 you
+   can ensure that the link to origin is permanently set by using the
+   ``--set-upstream`` option::
+   
+      git push --set-upstream origin my-new-feature
+   
+   From now on git_ will know that ``my-new-feature`` is related to the
+   ``my-new-feature`` branch in your own github_ repo. Subsequent push calls
+   are then simplified to the following::
+
+      git push
+   
+   You have to use ``--set-upstream`` for each new branch that you create.
+    
+
+It may be the case that while you were working on your edits, new commits have
+been added to ``upstream`` that affect your work. In this case, follow the
+:ref:`rebasing-on-master` section of this document to apply those changes to
+your branch.
 
 .. _writing-the-commit-message:
 
@@ -195,27 +207,71 @@ Standard acronyms to start the commit message with are::
    REL: related to releasing numpy
 
 
+.. _asking-for-merging:
+
+Asking for your changes to be merged with the main repo
+=======================================================
+
+When you feel your work is finished, you can create a pull request (PR). Github
+has a nice help page that outlines the process for `filing pull requests`_. 
+
+If your changes involve modifications to the API or addition/modification of a
+function, you should initiate a code review. This involves sending an email to
+the `NumPy mailing list`_ with a link to your PR along with a description of
+and a motivation for your changes.
+
+.. _pushing-to-main:
+
+Pushing changes to the main repo
+================================
+
+*This is only relevant if you have commit rights to the main Numpy repo.*
+
+When you have a set of "ready" changes in a feature branch ready for
+Numpy's ``master`` or ``maintenance`` branches, you can push
+them to ``upstream`` as follows:
+
+1. First, merge or rebase on the target branch.
+
+   a) Only a few, unrelated commits then prefer rebasing::
+
+        git fetch upstream
+        git rebase upstream/master
+
+      See :ref:`rebasing-on-master`.
+
+   b) If all of the commits are related, create a merge commit::
+
+        git fetch upstream
+        git merge --no-ff upstream/master
+
+2. Check that what you are going to push looks sensible::
+
+        git log -p upstream/master..
+        git log --oneline --graph
+
+3. Push to upstream::
+
+        git push upstream my-feature-branch:master
+
+.. note:: 
+
+    It's usually a good idea to use the ``-n`` flag to ``git push`` to check
+    first that you're about to push the changes you want to the place you
+    want.
+
+
 .. _rebasing-on-master:
 
 Rebasing on master
 ==================
 
 This updates your feature branch with changes from the upstream `NumPy
-github`_ repo. If you do not absolutely need to do this, try to avoid
-doing it, except perhaps when you are finished.
-
-First, it can be useful to update your master branch::
-
-   # go to the master branch
-   git checkout master
-   # pull changes from github
-   git fetch upstream
-   # update the master branch
-   git rebase upstream/master
-   # push it to your Github repo
-   git push
-
-Then, the feature branch::
+github`_ repo. If you do not absolutely need to do this, try to avoid doing
+it, except perhaps when you are finished. The first step will be to update
+your master branch with new commits from upstream. This is done in the same
+manner as described at the beginning of :ref:`making-a-new-feature-branch`.
+Next, you need to update the feature branch::
 
    # go to the feature branch
    git checkout my-new-feature
@@ -225,15 +281,17 @@ Then, the feature branch::
    git rebase master
 
 If you have made changes to files that have changed also upstream,
-this may generate merge conflicts that you need to resolve.
-Finally, remove the backup branch once the rebase succeeded::
+this may generate merge conflicts that you need to resolve. See
+:ref:`below<recovering-from-mess-up>` for help in this case.
+
+Finally, remove the backup branch upon a successful rebase::
 
    git branch -D tmp
 
 .. _recovering-from-mess-up:
 
 Recovering from mess-ups
-------------------------
+========================
 
 Sometimes, you mess up merges or rebases. Luckily, in Git it is
 relatively straightforward to recover from such mistakes.
@@ -262,100 +320,8 @@ If you forgot to make a backup branch::
 
 If you didn't actually mess up but there are merge conflicts, you need to
 resolve those.  This can be one of the trickier things to get right.  For a
-good description of how to do this, see
-http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts
-
-
-.. _asking-for-merging:
-
-Asking for your changes to be merged with the main repo
-=======================================================
-
-When you feel your work is finished, you can ask for code review, or
-directly file a pull request.
-
-Asking for code review
-----------------------
-
-#. Go to your repo URL - e.g. ``http://github.com/your-user-name/numpy``.
-#. Click on the *Branch list* button:
-
-   .. image:: branch_list.png
-
-#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
-
-   .. image:: branch_list_compare.png
-
-#. 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 `NumPy mailing list`_, asking for
-   review.  The URL will look something like:
-   ``http://github.com/your-user-name/numpy/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`.
-
-Filing a pull request
----------------------
-
-When you are ready to ask for the merge of your code:
-
-#. Go to the URL of your forked repo, say
-   ``http://github.com/your-user-name/numpy.git``.
-#. Click on the 'Pull request' button:
-
-   .. image:: pull_button.png
-
-   Enter a message; we suggest you select only ``NumPy`` as the
-   recipient.  The message will go to the NumPy core developers.  Please
-   feel free to add others from the list as you like.
-
-
-.. _pushing-to-main:
-
-Pushing changes to the main repo
-================================
-
-When you have a set of "ready" changes in a feature branch ready for
-Numpy's ``master`` or ``maintenance/1.5.x`` branches, you can push
-them to ``upstream`` as follows:
-
-1. First, merge or rebase on the target branch.
-
-   a) Only a few commits: prefer rebasing::
-
-          git fetch upstream
-	  git rebase upstream/master
-
-      See :ref:`above <rebasing-on-master>`.
-
-   b) Many related commits: consider creating a merge commit::
-
-          git fetch upstream
-	  git merge --no-ff upstream/master
-
-2. Check that what you are going to push looks sensible::
-
-       git log -p upstream/master..
-       git log --oneline --graph
-
-3. Push to upstream::
-
-       git push upstream my-feature-branch:master
-
-.. note::
+good description of how to do this, see `this article on merging conflicts`_.
 
-   Avoid using ``git pull`` here.
 
 Additional things you might want to do
 ######################################