remove duplication in git guidelines

1 files changed, 67 insertions, 85 deletions

diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide
index e7d73852f..37364e118 100644
--- a/Etc/zsh-development-guide
+++ b/Etc/zsh-development-guide
@@ -57,35 +57,80 @@ Patches
 
 Git Workflow
 ------------
+
+Zsh has migrated from CVS to git for version control. Thus far, we have
+avoided further changes to our workflow.
  
  * To allow changesets to be cross-referenced between the mailing list
    archives and version control history, commit messages should start with
    the mailing list sequence number. This number is generated by the list
-   server and inserted as an X-Seq: header field in the e-mail. To add
-   the number, you can use "git commit --amend" to change the commit.
+   server and inserted as an X-Seq: header field in the e-mail.
  
+ * An entry in the ChangeLog file should be added manually before pushing
+   a commit to the master repository. Don't create a separate change for
+   this: amend the existing commit in your local repository.
+
  * Do not merge your private feature branches onto the master branch: a
    linear history without merge commits is simpler to follow (and to
-   bisect). Both "git cherry-pick" and "git merge --ff-only" can be used
-   bring changes over to another branch without a merge commit.
- 
- * It is often useful to regularly check in changes while prototyping a
-   solution on a private branch. When finished, it is better to deliver a
-   clean history. For small changes, use "git merge --squash" to get a
-   single changeset for the feature. Where a change can be logically
-   divided into separate changesets use "git rebase -i master" from the
-   feature branch and squash your many intermediate steps into
-   appropriate changesets that each do something meaningful. Post each
-   changeset separately to the mailing list.
- 
- * Before pushing your changes to the main zsh repository, you can use
-   "git pull --rebase" to fetch any new updates from the server and
-   rebase your changes on top of them. You can also use "git rebase
-   master" from your feature branches.
- 
- * Patches can be prepared for the mailing list with "git format-patch
-   origin/master". To apply patches from a mailing list message, you can
-   use "git am".
+   bisect).
+
+Use of Git
+----------
+
+Micro Git Tutorial:
+
+  % $VISUAL file1.c file2.c new-file3.c
+  % git add new-file3.c
+  % git commit -a
+  % git push
+
+ "git commit -a" automatically finds files which are tracked and have
+ been modified, but doesn't pick up new files; "git add" adds a file to
+ the index to be part of the next commit, and can be used for new files
+ or for existing files (commit -a is a shortcut for the latter)
+
+ "git push" assumes that you're on the master branch and the repository
+ was created by cloning it from some place, with default options.
+
+Using a Local Feature Branch:
+
+  % git checkout -b feature_foo
+  % $VISUAL path/to/files ...
+  % git commit -a
+  [ generate single patch for changes ]
+  % git diff master
+  [ do mailing-list stuff here ]
+  [ Switch back to master: ]
+  % git checkout master
+  [ and get the most recent changes: ]
+  % git pull
+  [ make the branch content now be relative to *new* master tip ]
+  % git checkout feature_foo
+  % git rebase master
+  [ then bring in your changes: ]
+  % git checkout master
+  % git merge --squash feature_foo
+  % $VISUAL ChangeLog
+  % git add ChangeLog
+  % git commit --amend
+  % git push
+  [ cleanup ]
+  % git branch -d feature_foo
+
+  The above assumes you want all your changes on the feature branch to be
+  seen as a single change publicly. The normal git way to generate patches
+  is to use git format-patch which produces separate patches already
+  prepared for e-mailing. If you want to keep changes separate, don't use
+  the --squash option to git merge. In this case, it can be wise to use
+  --ff-only which ensures that you don't get a merge commit by only doing
+  the merge if the master can be trivially moved forward. An alternative is
+  to use git cherry-pick to pick out individual changes.
+
+Git further reading:
+ * git help tutorial
+ * git help tutorial-2
+ * git help gitcore-tutorial
+ * http://www-cs-students.stanford.edu/~blynn/gitmagic/
 
 Testing
 -------
@@ -901,66 +946,3 @@ The following parameters are currently used:
   distribution, but that need to be present in the git tree.  This
   variable is not used by the zsh build process and is present for
   the convenience of external checks.
-
-
-Use of Git
-----------
-
-zsh has migrated from CVS to git for version control.  We have so far
-kept our workflow unchanged; to wit:
-
- 1. change is developed and posted to the zsh-workers mailing list
- 2. the zsh-workers list management software adds an X-Seq: header
- 3. an entry is added to ChangeLog with details, including the X-Seq:
-    header.
-    [Open Question: should the first 6 or so characters of the commit
-     fingerprint be included, so: "* 12345/deadbeef: frobbed the baz" ?]
- 4. this is committed to git as a second commit
- 5. this is pushed to the master server
-
-Micro Git Tutorial:
-
-  % $VISUAL file1.c file2.c new-file3.c
-  % git add new-file3.c
-  % git commit -a
-  % git push
-
- "git commit -a" automatically finds files which are tracked and have
- been modified, but doesn't pick up new files; "git add" adds a file to
- the index to be part of the next commit, and can be used for new files
- or for existing files (commit -a is a shortcut for the latter)
-
- "git push" assumes that you're on the master branch and the repository
- was created by cloning it from some place, with default options.
-
-Feature branch work:
-
-  % git checkout -b feature_foo
-  % $VISUAL path/to/files ...
-  % git commit -a
-  [lather, rinse, repeat]
-  % git push origin feature_foo
-  [ do mailing-list stuff here ]
-  [ Switch back to master: ]
-  % git checkout master
-  [ and get the most recent changes: ]
-  % git pull
-  [ make the branch content now be relative to *new* master tip ]
-  % git checkout feature_foo
-  % git rebase master
-  [ then bring in your changes: ]
-  % git checkout master
-  % git merge --ff-only feature_foo
-  % $VISUAL ChangeLog
-  % git commit -i ChangeLog
-  % git push
-  [ Cleanup: ]
-  % git branch -d feature_foo
-  % git push origin :feature_foo
-
-Git further reading:
- * git help tutorial
- * git help tutorial-2
- * git help gitcore-tutorial
- * http://www-cs-students.stanford.edu/~blynn/gitmagic/
-