diff options
Diffstat (limited to 'Etc/zsh-development-guide')
| -rw-r--r-- | Etc/zsh-development-guide | 113 |
1 files changed, 106 insertions, 7 deletions
diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide index db78f94a6..e7d73852f 100644 --- a/Etc/zsh-development-guide +++ b/Etc/zsh-development-guide @@ -39,7 +39,7 @@ Patches intelligently. Please make sure the filenames in the diff header are relative to the top-level directory of the zsh distribution; for example, it should say "Src/init.c" rather than "init.c" or - "zsh/Src/init.c". + "zsh/Src/init.c". Git-style naming of diffs is also acceptable. * Please put only one bug fix or feature enhancement in a single patch and only one patch per mail message. This helps me to multiplex the many @@ -52,9 +52,40 @@ Patches * Please test your patch and make sure it applies cleanly. It takes considerably more time to manually merge a patch into the baseline code. -* There is now a zsh patch archive. To have your patches appear in the - archive, send them to the mailing list with a Subject: line starting - with "PATCH:". +* 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 ------- @@ -167,6 +198,11 @@ C coding style also #include other system headers. It *must not* #include any other module's headers or any other .pro files. +* The repository includes a `.editorconfig' file with whitespace/indent + control settings. Information about text editor plugins and this file + can be found at <http://editorconfig.org/>. + + Modules ------- @@ -841,13 +877,13 @@ Distribution of files --------------------- zsh is distributed in two parts: a "src" distribution containing all -the source files (roughly, but not exactly, corresponding to the CVS +the source files (roughly, but not exactly, corresponding to the git tree), and a "doc" distribution containing some pre-built files from the documentation directory. All the files in the "doc" distribution may be generated from files in the "src" distribution with appropriate freely available tools. -To indicate which files should be distributed, each directory in the CVS +To indicate which files should be distributed, each directory in the git tree includes a file .distfiles that sets any number of a set of Bourne shell (scalar) parameters. The value of the parameter is expanded as a set of standard command line arguments. Basic globbing is allowed in the @@ -862,6 +898,69 @@ The following parameters are currently used: distribution. - DISTFILES_NOT is a list of files that will not be included in a - distribution, but that need to be present in the CVS tree. This + 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/ + |