diff options
Diffstat (limited to 'Documentation/howto/maintain-git.txt')
| -rw-r--r-- | Documentation/howto/maintain-git.txt | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt new file mode 100644 index 0000000000..4357e26913 --- /dev/null +++ b/Documentation/howto/maintain-git.txt @@ -0,0 +1,277 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Wed, 21 Nov 2007 16:32:55 -0800 +Subject: Addendum to "MaintNotes" +Abstract: Imagine that git development is racing along as usual, when our friendly + neighborhood maintainer is struck down by a wayward bus. Out of the + hordes of suckers (loyal developers), you have been tricked (chosen) to + step up as the new maintainer. This howto will show you "how to" do it. + +The maintainer's git time is spent on three activities. + + - Communication (60%) + + Mailing list discussions on general design, fielding user + questions, diagnosing bug reports; reviewing, commenting on, + suggesting alternatives to, and rejecting patches. + + - Integration (30%) + + Applying new patches from the contributors while spotting and + correcting minor mistakes, shuffling the integration and + testing branches, pushing the results out, cutting the + releases, and making announcements. + + - Own development (10%) + + Scratching my own itch and sending proposed patch series out. + +The policy on Integration is informally mentioned in "A Note +from the maintainer" message, which is periodically posted to +this mailing list after each feature release is made. + +The policy. + + - Feature releases are numbered as vX.Y.Z and are meant to + contain bugfixes and enhancements in any area, including + functionality, performance and usability, without regression. + + - Maintenance releases are numbered as vX.Y.Z.W and are meant + to contain only bugfixes for the corresponding vX.Y.Z feature + release and earlier maintenance releases vX.Y.Z.V (V < W). + + - 'master' branch is used to prepare for the next feature + release. In other words, at some point, the tip of 'master' + branch is tagged with vX.Y.Z. + + - 'maint' branch is used to prepare for the next maintenance + release. After the feature release vX.Y.Z is made, the tip + of 'maint' branch is set to that release, and bugfixes will + accumulate on the branch, and at some point, the tip of the + branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on. + + - 'next' branch is used to publish changes (both enhancements + and fixes) that (1) have worthwhile goal, (2) are in a fairly + good shape suitable for everyday use, (3) but have not yet + demonstrated to be regression free. New changes are tested + in 'next' before merged to 'master'. + + - 'pu' branch is used to publish other proposed changes that do + not yet pass the criteria set for 'next'. + + - The tips of 'master', 'maint' and 'next' branches will always + fast forward, to allow people to build their own + customization on top of them. + + - Usually 'master' contains all of 'maint', 'next' contains all + of 'master' and 'pu' contains all of 'next'. + + - The tip of 'master' is meant to be more stable than any + tagged releases, and the users are encouraged to follow it. + + - The 'next' branch is where new action takes place, and the + users are encouraged to test it so that regressions and bugs + are found before new topics are merged to 'master'. + + +A typical git day for the maintainer implements the above policy +by doing the following: + + - Scan mailing list and #git channel log. Respond with review + comments, suggestions etc. Kibitz. Collect potentially + usable patches from the mailing list. Patches about a single + topic go to one mailbox (I read my mail in Gnus, and type + \C-o to save/append messages in files in mbox format). + + - Review the patches in the saved mailboxes. Edit proposed log + message for typofixes and clarifications, and add Acks + collected from the list. Edit patch to incorporate "Oops, + that should have been like this" fixes from the discussion. + + - Classify the collected patches and handle 'master' and + 'maint' updates: + + - Obviously correct fixes that pertain to the tip of 'maint' + are directly applied to 'maint'. + + - Obviously correct fixes that pertain to the tip of 'master' + are directly applied to 'master'. + + This step is done with "git am". + + $ git checkout master ;# or "git checkout maint" + $ git am -3 -s mailbox + $ make test + + - Merge downwards (maint->master): + + $ git checkout master + $ git merge maint + $ make test + + - Review the last issue of "What's cooking" message, review the + topics scheduled for merging upwards (topic->master and + topic->maint), and merge. + + $ git checkout master ;# or "git checkout maint" + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ git log -p ORIG_HEAD.. ;# final review + $ git diff ORIG_HEAD.. ;# final review + $ make test ;# final review + $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic" + + - Merge downwards (maint->master) if needed: + + $ git checkout master + $ git merge maint + $ make test + + - Merge downwards (master->next) if needed: + + $ git checkout next + $ git merge master + $ make test + + - Handle the remaining patches: + + - Anything unobvious that is applicable to 'master' (in other + words, does not depend on anything that is still in 'next' + and not in 'master') is applied to a new topic branch that + is forked from the tip of 'master'. This includes both + enhancements and unobvious fixes to 'master'. A topic + branch is named as ai/topic where "ai" is typically + author's initial and "topic" is a descriptive name of the + topic (in other words, "what's the series is about"). + + - An unobvious fix meant for 'maint' is applied to a new + topic branch that is forked from the tip of 'maint'. The + topic is named as ai/maint-topic. + + - Changes that pertain to an existing topic are applied to + the branch, but: + + - obviously correct ones are applied first; + + - questionable ones are discarded or applied to near the tip; + + - Replacement patches to an existing topic are accepted only + for commits not in 'next'. + + The above except the "replacement" are all done with: + + $ git am -3 -s mailbox + + while patch replacement is often done by: + + $ git format-patch ai/topic~$n..ai/topic ;# export existing + + then replace some parts with the new patch, and reapplying: + + $ git reset --hard ai/topic~$n + $ git am -3 -s 000*.txt + + The full test suite is always run for 'maint' and 'master' + after patch application; for topic branches the tests are run + as time permits. + + - Update "What's cooking" message to review the updates to + existing topics, newly added topics and graduated topics. + + This step is helped with Meta/UWC script (where Meta/ contains + a checkout of the 'todo' branch). + + - Merge topics to 'next'. For each branch whose tip is not + merged to 'next', one of three things can happen: + + - The commits are all next-worthy; merge the topic to next: + + $ git checkout next + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ make test + + - The new parts are of mixed quality, but earlier ones are + next-worthy; merge the early parts to next: + + $ git checkout next + $ git merge ai/topic~2 ;# the tip two are dubious + $ make test + + - Nothing is next-worthy; do not do anything. + + - Rebase topics that do not have any commit in next yet. This + step is optional but sometimes is worth doing when an old + series that is not in next can take advantage of low-level + framework change that is merged to 'master' already. + + $ git rebase master ai/topic + + This step is helped with Meta/git-topic.perl script to + identify which topic is rebaseable. There also is a + pre-rebase hook to make sure that topics that are already in + 'next' are not rebased beyond the merged commit. + + - Rebuild "pu" to merge the tips of topics not in 'next'. + + $ git checkout pu + $ git reset --hard next + $ git merge ai/topic ;# repeat for all remaining topics + $ make test + + This step is helped with Meta/PU script + + - Push four integration branches to a private repository at + k.org and run "make test" on all of them. + + - Push four integration branches to /pub/scm/git/git.git at + k.org. This triggers its post-update hook which: + + (1) runs "git pull" in $HOME/git-doc/ repository to pull + 'master' just pushed out; + + (2) runs "make doc" in $HOME/git-doc/, install the generated + documentation in staging areas, which are separate + repositories that have html and man branches checked + out. + + (3) runs "git commit" in the staging areas, and run "git + push" back to /pub/scm/git/git.git/ to update the html + and man branches. + + (4) installs generated documentation to /pub/software/scm/git/docs/ + to be viewed from http://www.kernel.org/ + + - Fetch html and man branches back from k.org, and push four + integration branches and the two documentation branches to + repo.or.cz + + +Some observations to be made. + + * Each topic is tested individually, and also together with + other topics cooking in 'next'. Until it matures, none part + of it is merged to 'master'. + + * A topic already in 'next' can get fixes while still in + 'next'. Such a topic will have many merges to 'next' (in + other words, "git log --first-parent next" will show many + "Merge ai/topic to next" for the same topic. + + * An unobvious fix for 'maint' is cooked in 'next' and then + merged to 'master' to make extra sure it is Ok and then + merged to 'maint'. + + * Even when 'next' becomes empty (in other words, all topics + prove stable and are merged to 'master' and "git diff master + next" shows empty), it has tons of merge commits that will + never be in 'master'. + + * In principle, "git log --first-parent master..next" should + show nothing but merges (in practice, there are fixup commits + and reverts that are not merges). + + * Commits near the tip of a topic branch that are not in 'next' + are fair game to be discarded, replaced or rewritten. + Commits already merged to 'next' will not be. + + * Being in the 'next' branch is not a guarantee for a topic to + be included in the next feature release. Being in the + 'master' branch typically is. |