Fixes git workflow

* overhauls the docs so they're (hopefully) clearer on the git
  workflow
* adds text about putting things in bugfix branches, documenting
  your work, and using the issue tracker
* adds a contrived example that uses aliens

1 files changed, 154 insertions, 30 deletions

diff --git a/docs/git.rst b/docs/git.rst
index 0db1dacf..ddbcf226 100644
--- a/docs/git.rst
+++ b/docs/git.rst
@@ -2,11 +2,17 @@
  Git, Cloning and Patches
 ==========================
 
-GNU MediaGoblin uses git for all our version control and we have
-the repositories hosted on `Gitorious <http://gitorious.org/>`_.
+GNU MediaGoblin uses git for all our version control and we have the
+repositories hosted on `Gitorious <http://gitorious.org/>`_.  We have
+two repositories:
 
-We have two repositories.  One is for the project and the other is for
-the project website.
+* MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin
+* MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website
+
+It's most likely you want to look at the software repository--not the
+website one.
+
+The rest of this chapter talks about using the software repository.
 
 
 How to clone the project
@@ -20,46 +26,164 @@ Do::
 How to send in patches
 ======================
 
+**Tie your changes to issues in the issue tracker**
+
 All patches should be tied to issues in the `issue tracker
-<http://bugs.foocorp.net/projects/mediagoblin/issues>`_.
-That makes it a lot easier for everyone to track proposed changes and
-make sure your hard work doesn't get dropped on the floor!
+<http://bugs.foocorp.net/projects/mediagoblin/issues>`_.  That makes
+it a lot easier for everyone to track proposed changes and make sure
+your hard work doesn't get dropped on the floor!  If there isn't an
+issue for what you're working on, please create one.  The better the
+description of what it is you're trying to fix/implement, the better
+everyone else is able to understand why you're doing what you're
+doing.
+
+**Use bugfix branches**
+
+The best way to isolate your changes is to create a branch based off
+of the MediaGoblin repository master branch, do the changes related to
+that one issue there, and then let us know how to get it.
+
+It's much easier on us if you isolate your changes to a branch focused
+on the issue.  Then we don't have to sift through things.
+
+It's much easier on you if you isolate your changes to a branch
+focused on the issue.  Then when we merge your changes in, you just
+have to do a ``git fetch`` and that's it.  This is especially true if
+we reject some of your changes, but accept others or otherwise tweak
+your changes.
+
+Further, if you isolate your changes to a branch, then you can work on
+multiple issues at the same time and they don't conflict with one
+another.
+
+**Properly document your changes**
+
+Include comments in the code.
+
+Write comprehensive commit messages.  The better your commit message
+is at describing what you did and why, the easier it is for us to
+quickly accept your patch.
+
+Write comprehensive comments in the issue tracker about what you're
+doing and why.
+
+
+**How to send us your changes**
+
+There are three ways to let us know how to get it:
+
+1. (preferred) **push changes to publicly available git clone and let
+   us know where to find it**
+
+   Push your branch to your publicly available git clone and add a
+   comment to the issue with the url for your clone and the branch to
+   look at.
+
+2. **attaching the patch files to the issue**
+
+   Run::
+
+       git format-patch -o patches <remote>/master
+       
+   Then tar up the newly created ``patches`` directory and attach the
+   directory to the issue.
+
+
+Example workflow
+================
+Here's an example workflow.
+
+
+Contributing changes
+--------------------
+
+Slartibartfast from the planet Magrathea far off in the universe has
+decided that he is bored with fjords and wants to fix issue 42 and
+send us the changes.
+
+Slartibartfast has cloned the MediaGoblin repository and his clone
+lives on gitorious.
+
+Slartibartfast works locally.  The remote named ``origin`` points to
+his clone on gitorious.  The remote named ``gmg`` points to the
+MediaGoblin repository.
+
+Slartibartfast does the following:
+
+1. Fetches the latest from the MediaGoblin repository::
+
+       git fetch --all -p
+
+2. Creates a branch from the tip of the MediaGoblin repository (the
+   remote is named ``gmg``) master branch called ``issue_42``::
+
+       git checkout -b issue_42 gmg/master
+
+3. Slartibartfast works hard on his changes in the ``issue_42``
+   branch.  When done, he wants to notify us that he has made changes
+   he wants us to see.
+
+4. Slartibartfast pushes his changes to his clone (the remote is named
+   ``origin``)::
+
+       git push origin issue_42
+
+5. Slartibartfast adds a comment to issue 42 with the url for his
+   repository and the name of the branch he put the code in.  He also
+   explains what he did and why it addresses the issue.
+
+
+Updating a contribution
+-----------------------
+
+Slartibartfast brushes his hands off with the sense of accomplishment
+that comes with the knowledge of a job well done.  He stands, wanders
+over to get a cup of water, then realizes that he forgot to run the
+unit tests!
+
+He runs the unit tests and discovers there's a bug in the code!
+
+Then he does this:
+
+1. He checks out the ``issue_42`` branch::
 
-If there isn't an issue for what you're working on, please create
-one.  The better the description of what it is you're trying to
-fix/implement, the better everyone else is able to understand why
-you're doing what you're doing.
+       git checkout issue_42
 
-There are two ways you could send in a patch.
+2. He fixes the bug and checks it into the ``issue_42`` branch.
 
+3. He pushes his changes to his clone (the remote is named ``origin``)::
 
-How to send in a patch from a publicly available clone
-------------------------------------------------------
+       git push origin issue_42
 
-Add a comment to the issue you're working on with the following bits
-of information:
+4. He adds another comment to issue 42 explaining about the mistake
+   and how he fixed it and that he's pushed the new change to the
+   ``issue_42`` branch of his publicly available clone.
 
-* the url for your clone
-* the revs you want looked at
-* any details, questions, or other things that should be known
 
+What happens next
+-----------------
 
-How to send in a patch if you don't have a publicly available clone
--------------------------------------------------------------------
+Slartibartfast is once again happy with his work.  He finds issue 42
+in the issue tracker and adds a comment saying he submitted a merge
+request with his changes and explains what they are.
 
-Assuming that the remote is our repository on gitorious and the branch
-to compare against is master, do the following:
+Later, someone checks out his code and finds a problem with it.  He
+adds a comment to the issue tracker specifying the problem and asks
+Slartibartfast to fix it.  Slartibartfst goes through the above steps
+again, fixes the issue, pushes it to his ``issue_42`` branch and adds
+another comment to the issue tracker about how he fixed it.
 
-1. checkout the branch you did your work in
-2. do::
+Later, someone checks out his code and is happy with it.  Someone
+pulls it into the master branch of the MediaGoblin repository and adds
+another comment to the issue and probably closes the issue out.
 
-      git format-patch -o patches origin/master
+Slartibartfast is notified of this.  Slartibartfast does a::
 
-3. either:
+   git fetch --all
 
-   * tar up and attach the tarball to the issue you're working on, OR
-   * attach the patch files to the issue you're working on one at a
-     time
+The changes show up in the ``master`` branch of the ``gmg`` remote.
+Slartibartfast now deletes his ``issue_42`` branch because he doesn't
+need it anymore.
 
 
 How to learn git