Add some clarifications and comments to the gitwash instructions based on my newbie experience.

astropy-buildbot · astropy-buildbot · commit 586baec91934 · 2011-02-26T08:18:38.000-05:00
diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst
@@ -32,6 +32,12 @@ Making a new feature branch
    git branch my-new-feature
    git checkout my-new-feature
 
+This will create a feature branch based on ``master``.  To create a
+feature branch based on a maintenance branch, use::
+
+   git branch my-new-feature remotes/origin/v1.0.x
+   git checkout my-new-feature
+
 Generally, you will want to keep this also on your public github_ fork
 of matplotlib_.  To do this, you `git push`_ this new branch up to your github_
 repo.  Generally (if you followed the instructions in these pages, and
@@ -40,13 +46,15 @@ by default), git will have a link to your github_ repo, called
 
    git push origin my-new-feature
 
-In git >1.7 you can ensure that the link is correctly set by using the
-``--set-upstream`` option::
+You will need to use this exact command, rather than simply ``git
+push`` every time you want to push changes on your feature branch to
+your github_ repo.  However, in git >1.7 you can set up a link 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 the github_ repo.
+and then next time you need to push changes to your branch a simple
+``git push`` will suffice.
 
 The editing workflow
 ====================
@@ -125,7 +133,7 @@ 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`.
 
-Asking for your changes to be merged with the main repo
+Asking for your changes to be merged into the main repo
 =======================================================
 
 When you are ready to ask for the merge of your code:
@@ -140,10 +148,15 @@ When you are ready to ask for the merge of your code:
    recipient.  The message will go to the `matplotlib mailing list`_.  Please
    feel free to add others from the list as you like.
 
-Merging from trunk
-==================
+#. 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.
 
-This updates your code from the upstream `matplotlib github`_  repo.
+Staying up to date with changes in the central repository
+=========================================================
+
+This updates your working copy from the upstream `matplotlib github`_
+repo.
 
 Overview
 --------
@@ -177,6 +190,14 @@ then merging into your current branch::
 
    git merge upstream/master
 
+.. Doesn't one then need to push this up to the private repository? I
+.. have multiple machines I use for development, and I don't want to
+.. have to do this on all of them - MGD
+
+.. Does this need to be done for each maintenance branch as well?
+.. This doesn't seem to be sufficient to pull in changes on an
+.. upstream maintenance branch. - MGD
+
 Deleting a branch on github_
 ============================
 
diff --git a/doc/devel/gitwash/set_up_fork.rst b/doc/devel/gitwash/set_up_fork.rst
@@ -56,12 +56,17 @@ Note that we've used ``git://`` for the URL rather than ``git@``.  The
 (or deliberately) write to the upstream repo, and we are only going to
 use it to merge into our own code.
 
+Note this command needs to be run on every clone of the repository
+that you make.  It is not tracked in your personal repository on
+github_.
+
 Just for your own satisfaction, show yourself that you now have a new
 'remote', with ``git remote -v show``, giving you something like::
 
-   upstream	git://github.com/matplotlib/matplotlib.git (fetch)
-   upstream	git://github.com/matplotlib/matplotlib.git (push)
-   origin	git@github.com:your-user-name/matplotlib.git (fetch)
-   origin	git@github.com:your-user-name/matplotlib.git (push)
+   upstream     git://github.com/matplotlib/matplotlib.git (fetch)
+   upstream     git://github.com/matplotlib/matplotlib.git (push)
+   origin       git@github.com:your-user-name/matplotlib.git (fetch)
+   origin       git@github.com:your-user-name/matplotlib.git (push)
 
 .. include:: links.inc
+
