From 0a8c28b3d655b52bc600e052db1da43bf4a98bae Mon Sep 17 00:00:00 2001 From: Oliver Kiddle Date: Tue, 12 Feb 2013 10:39:59 +0000 Subject: remove duplication in git guidelines --- Etc/zsh-development-guide | 152 ++++++++++++++++++++-------------------------- 1 file changed, 67 insertions(+), 85 deletions(-) (limited to 'Etc') 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/ - -- cgit 1.4.1