DOC: expand sections on commit messages and merging/rebasing in the devguide.

This commit address comments from Charles on PR #455.

1 files changed, 16 insertions, 2 deletions

diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst
index cf7c26965..8606b9018 100644
--- a/doc/source/dev/gitwash/development_workflow.rst
+++ b/doc/source/dev/gitwash/development_workflow.rst
@@ -152,11 +152,14 @@ In more detail
    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 `git commit`_ manual
-   page might also be useful.
+   `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`). 
 
+
+.. _writing-the-commit-message:
+
 Writing the commit message
 --------------------------
 
@@ -170,6 +173,12 @@ Commit messages should be clear and follow a few basic rules.  Example::
    characters.  If the commit is related to a ticket, indicate that with
    "See #3456", "See ticket 3456", "Closes #3456" or similar.
 
+Describing the motivation for a change, the nature of a bug for bug fixes or
+some details on what an enhancement does are also good to include in a commit
+message.  Messages should be understandable without looking at the code
+changes.  A commit message like ``MAINT: fixed another one`` is an example of
+what not to do; the reader has to go look for context elsewhere.
+
 Standard acronyms to start the commit message with are::
 
    API: an (incompatible) API change
@@ -251,6 +260,11 @@ If you forgot to make a backup branch::
    # reset the branch to where it was before the botched rebase
    git reset --hard my-feature-branch@{2}
 
+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: