diff options
Diffstat (limited to 'third_party/git/Documentation/howto/maintain-git.txt')
| -rw-r--r-- | third_party/git/Documentation/howto/maintain-git.txt | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/third_party/git/Documentation/howto/maintain-git.txt b/third_party/git/Documentation/howto/maintain-git.txt deleted file mode 100644 index a67130debb63..000000000000 --- a/third_party/git/Documentation/howto/maintain-git.txt +++ /dev/null @@ -1,475 +0,0 @@ -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. -Content-type: text/asciidoc - -How to maintain Git -=================== - -Activities ----------- - -The maintainer's Git time is spent on three activities. - - - Communication (45%) - - Mailing list discussions on general design, fielding user - questions, diagnosing bug reports; reviewing, commenting on, - suggesting alternatives to, and rejecting patches. - - - Integration (50%) - - 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 (5%) - - Scratching my own itch and sending proposed patch series out. - -The Policy ----------- - -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. - - - Feature releases are numbered as vX.Y.0 and are meant to - contain bugfixes and enhancements in any area, including - functionality, performance and usability, without regression. - - - One release cycle for a feature release is expected to last for - eight to ten weeks. - - - Maintenance releases are numbered as vX.Y.Z and are meant - to contain only bugfixes for the corresponding vX.Y.0 feature - release and earlier maintenance releases vX.Y.W (W < Z). - - - '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.0. - - - 'maint' branch is used to prepare for the next maintenance - release. After the feature release vX.Y.0 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.1, vX.Y.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'. - - - 'seen' branch is used to publish other proposed changes that do - not yet pass the criteria set for 'next'. - - - The tips of 'master' and 'maint' branches will not be rewound to - allow people to build their own customization on top of them. - Early in a new development cycle, 'next' is rewound to the tip of - 'master' once, but otherwise it will not be rewound until the end - of the cycle. - - - Usually 'master' contains all of 'maint' and 'next' contains all - of 'master'. 'seen' contains all the topics merged to 'next', but - is rebuilt directly on 'master'. - - - 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'. - -Note that before v1.9.0 release, the version numbers used to be -structured slightly differently. vX.Y.Z were feature releases while -vX.Y.Z.W were maintenance releases for vX.Y.Z. - - -A Typical Git Day ------------------ - -A typical Git day for the maintainer implements the above policy -by doing the following: - - - Scan mailing list. 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). - - - Write his own patches to address issues raised on the list but - nobody has stepped up solving. Send it out just like other - contributors do, and pick them up just like patches from other - contributors (see above). - - - 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'. - - - Other topics are not handled in this step. - - This step is done with "git am". - - $ git checkout master ;# or "git checkout maint" - $ git am -sc3 mailbox - $ make test - - In practice, almost no patch directly goes to 'master' or - 'maint'. - - - Review the last issue of "What's cooking" message, review the - topics ready for merging (topic->master and topic->maint). Use - "Meta/cook -w" script (where Meta/ contains a checkout of the - 'todo' branch) to aid this step. - - And perform the merge. Use "Meta/Reintegrate -e" script (see - later) to aid this step. - - $ Meta/cook -w last-issue-of-whats-cooking.mbox - - $ git checkout master ;# or "git checkout maint" - $ echo ai/topic | Meta/Reintegrate -e ;# "git merge ai/topic" - $ git log -p ORIG_HEAD.. ;# final review - $ git diff ORIG_HEAD.. ;# final review - $ make test ;# final review - - - 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' (or the last feature release, - which is a bit older than 'master'). This includes both - enhancements and unobvious fixes to 'master'. A topic - branch is named as ai/topic where "ai" is two-letter string - named after 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' (or the - oldest and still relevant maintenance branch). The - topic may be 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 initial round is done with: - - $ git checkout ai/topic ;# or "git checkout -b ai/topic master" - $ git am -sc3 mailbox - - and replacing an existing topic with subsequent round is done with: - - $ git checkout master...ai/topic ;# try to reapply to the same base - $ git am -sc3 mailbox - - to prepare the new round on a detached HEAD, and then - - $ git range-diff @{-1}... - $ git diff @{-1} - - to double check what changed since the last round, and finally - - $ git checkout -B @{-1} - - to conclude (the last step is why a topic already in 'next' is - not replaced but updated incrementally). - - Whether it is the initial round or a subsequent round, the topic - may not build even in isolation, or may break the build when - merged to integration branches due to bugs. There may already - be obvious and trivial improvements suggested on the list. The - maintainer often adds an extra commit, with "SQUASH???" in its - title, to fix things up, before publishing the integration - branches to make it usable by other developers for testing. - These changes are what the maintainer is not 100% committed to - (trivial typofixes etc. are often squashed directly into the - patches that need fixing, without being applied as a separate - "SQUASH???" commit), so that they can be removed easily as needed. - - - - Merge maint to master as needed: - - $ git checkout master - $ git merge maint - $ make test - - - Merge master to next as needed: - - $ git checkout next - $ git merge master - $ make test - - - Review the last issue of "What's cooking" again and see if topics - that are ready to be merged to 'next' are still in good shape - (e.g. has there any new issue identified on the list with the - series?) - - - Prepare 'jch' branch, which is used to represent somewhere - between 'master' and 'seen' and often is slightly ahead of 'next'. - - $ Meta/Reintegrate master..seen >Meta/redo-jch.sh - - The result is a script that lists topics to be merged in order to - rebuild 'seen' as the input to Meta/Reintegrate script. Remove - later topics that should not be in 'jch' yet. Add a line that - consists of '### match next' before the name of the first topic - in the output that should be in 'jch' but not in 'next' yet. - - - Now we are ready to start merging 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; - - The new parts are of mixed quality, but earlier ones are - next-worthy; merge the early parts to next; - - Nothing is next-worthy; do not do anything. - - This step is aided with Meta/redo-jch.sh script created earlier. - If a topic that was already in 'next' gained a patch, the script - would list it as "ai/topic~1". To include the new patch to the - updated 'next', drop the "~1" part; to keep it excluded, do not - touch the line. If a topic that was not in 'next' should be - merged to 'next', add it at the end of the list. Then: - - $ git checkout -B jch master - $ Meta/redo-jch.sh -c1 - - to rebuild the 'jch' branch from scratch. "-c1" tells the script - to stop merging at the first line that begins with '###' - (i.e. the "### match next" line you added earlier). - - At this point, build-test the result. It may reveal semantic - conflicts (e.g. a topic renamed a variable, another added a new - reference to the variable under its old name), in which case - prepare an appropriate merge-fix first (see appendix), and - rebuild the 'jch' branch from scratch, starting at the tip of - 'master'. - - Then do the same to 'next' - - $ git checkout next - $ sh Meta/redo-jch.sh -c1 -e - - The "-e" option allows the merge message that comes from the - history of the topic and the comments in the "What's cooking" to - be edited. The resulting tree should match 'jch' as the same set - of topics are merged on 'master'; otherwise there is a mismerge. - Investigate why and do not proceed until the mismerge is found - and rectified. - - $ git diff jch next - - When all is well, clean up the redo-jch.sh script with - - $ sh Meta/redo-jch.sh -u - - This removes topics listed in the script that have already been - merged to 'master'. This may lose '### match next' marker; - add it again to the appropriate place when it happens. - - - Rebuild 'seen'. - - $ Meta/Reintegrate master..seen >Meta/redo-seen.sh - - Edit the result by adding new topics that are not still in 'seen' - in the script. Then - - $ git checkout -B seen jch - $ sh Meta/redo-seen.sh - - When all is well, clean up the redo-seen.sh script with - - $ sh Meta/redo-seen.sh -u - - Double check by running - - $ git branch --no-merged seen - - to see there is no unexpected leftover topics. - - At this point, build-test the result for semantic conflicts, and - if there are, prepare an appropriate merge-fix first (see - appendix), and rebuild the 'seen' branch from scratch, starting at - the tip of 'jch'. - - - Update "What's cooking" message to review the updates to - existing topics, newly added topics and graduated topics. - - This step is helped with Meta/cook script. - - $ Meta/cook - - This script inspects the history between master..seen, finds tips - of topic branches, compares what it found with the current - contents in Meta/whats-cooking.txt, and updates that file. - Topics not listed in the file but are found in master..seen are - added to the "New topics" section, topics listed in the file that - are no longer found in master..seen are moved to the "Graduated to - master" section, and topics whose commits changed their states - (e.g. used to be only in 'seen', now merged to 'next') are updated - with change markers "<<" and ">>". - - Look for lines enclosed in "<<" and ">>"; they hold contents from - old file that are replaced by this integration round. After - verifying them, remove the old part. Review the description for - each topic and update its doneness and plan as needed. To review - the updated plan, run - - $ Meta/cook -w - - which will pick up comments given to the topics, such as "Will - merge to 'next'", etc. (see Meta/cook script to learn what kind - of phrases are supported). - - - Compile, test and install all four (five) integration branches; - Meta/Dothem script may aid this step. - - - Format documentation if the 'master' branch was updated; - Meta/dodoc.sh script may aid this step. - - - Push the integration branches out to public places; Meta/pushall - script may aid this step. - -Observations ------------- - -Some observations to be made. - - * Each topic is tested individually, and also together with other - topics cooking first in 'seen', then in 'jch' and then in 'next'. - Until it matures, no 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 branch '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. - - * Due to the nature of "SQUASH???" fix-ups, if the original author - agrees with the suggested changes, it is OK to squash them to - appropriate patches in the next round (when the suggested change - is small enough, the author should not even bother with - "Helped-by"). It is also OK to drop them from the next round - when the original author does not agree with the suggestion, but - the author is expected to say why somewhere in the discussion. - - -Appendix --------- - -Preparing a "merge-fix" -~~~~~~~~~~~~~~~~~~~~~~~ - -A merge of two topics may not textually conflict but still have -conflict at the semantic level. A classic example is for one topic -to rename an variable and all its uses, while another topic adds a -new use of the variable under its old name. When these two topics -are merged together, the reference to the variable newly added by -the latter topic will still use the old name in the result. - -The Meta/Reintegrate script that is used by redo-jch and redo-seen -scripts implements a crude but usable way to work this issue around. -When the script merges branch $X, it checks if "refs/merge-fix/$X" -exists, and if so, the effect of it is squashed into the result of -the mechanical merge. In other words, - - $ echo $X | Meta/Reintegrate - -is roughly equivalent to this sequence: - - $ git merge --rerere-autoupdate $X - $ git commit - $ git cherry-pick -n refs/merge-fix/$X - $ git commit --amend - -The goal of this "prepare a merge-fix" step is to come up with a -commit that can be squashed into a result of mechanical merge to -correct semantic conflicts. - -After finding that the result of merging branch "ai/topic" to an -integration branch had such a semantic conflict, say seen~4, check the -problematic merge out on a detached HEAD, edit the working tree to -fix the semantic conflict, and make a separate commit to record the -fix-up: - - $ git checkout seen~4 - $ git show -s --pretty=%s ;# double check - Merge branch 'ai/topic' to seen - $ edit - $ git commit -m 'merge-fix/ai/topic' -a - -Then make a reference "refs/merge-fix/ai/topic" to point at this -result: - - $ git update-ref refs/merge-fix/ai/topic HEAD - -Then double check the result by asking Meta/Reintegrate to redo the -merge: - - $ git checkout seen~5 ;# the parent of the problem merge - $ echo ai/topic | Meta/Reintegrate - $ git diff seen~4 - -This time, because you prepared refs/merge-fix/ai/topic, the -resulting merge should have been tweaked to include the fix for the -semantic conflict. - -Note that this assumes that the order in which conflicting branches -are merged does not change. If the reason why merging ai/topic -branch needs this merge-fix is because another branch merged earlier -to the integration branch changed the underlying assumption ai/topic -branch made (e.g. ai/topic branch added a site to refer to a -variable, while the other branch renamed that variable and adjusted -existing use sites), and if you changed redo-jch (or redo-seen) script -to merge ai/topic branch before the other branch, then the above -merge-fix should not be applied while merging ai/topic, but should -instead be applied while merging the other branch. You would need -to move the fix to apply to the other branch, perhaps like this: - - $ mf=refs/merge-fix - $ git update-ref $mf/$the_other_branch $mf/ai/topic - $ git update-ref -d $mf/ai/topic |