30877: document git workflow

1 files changed, 32 insertions, 0 deletions

diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide
index 9546f284a..e7d73852f 100644
--- a/Etc/zsh-development-guide
+++ b/Etc/zsh-development-guide
@@ -55,6 +55,38 @@ Patches
 * By convention, patches should be sent with a Subject: line starting with
   one of "PATCH:", "[PATCH]" or "[PATCH n/m]" (for a patch series).
 
+Git 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.
+ 
+ * 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".
+
 Testing
 -------