Some "implementation details" of how I perform these integration
tasks day to day have changed since the document was originally
written. Update to reflect the way things are currently done.
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Documentation/howto/maintain-git.txt | 106 ++++++++++++++++-----------
1 file changed, 63 insertions(+), 43 deletions(-)
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index 7219faf09f..41f54050f8 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -211,12 +211,12 @@ by doing the following:
The initial round is done with:
$ git checkout ai/topic ;# or "git checkout -b ai/topic master"
- $ git am -sc3 mailbox
+ $ git am -sc3 --whitespace=warn 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
+ $ git am -sc3 --whitespace=warn mailbox
to prepare the new round on a detached HEAD, and then
@@ -241,39 +241,59 @@ by doing the following:
(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.
+ The expectation is that the original author will make corrections
+ in a reroll.
+ - By now, new topic branches are created and existing topic
+ branches are updated. The integration branches 'next', 'jch',
+ and 'seen' need to be updated to contain them.
- - Merge maint to master as needed:
+ - If there are topics that have been merged to 'master' and should
+ be merged to 'maint', merge them to 'maint', and update the
+ release notes to the next maintenance release.
- $ git checkout master
- $ git merge maint
- $ make test
+ - Review the latest issue of "What's cooking" again. Are topics
+ that have been sufficiently long in 'next' ready to be merged to
+ 'master'? Are topics we saw earlier and are in 'seen' now got
+ positive reviews and are ready to be merged to 'next'?
- - Merge master to next as needed:
+ - If there are topics that have been cooking in 'next' long enough
+ and should be merged to 'master', merge them to 'master', and
+ update the release notes to the next feature release.
- $ git checkout next
- $ git merge master
- $ make test
+ - If there were patches directly made on 'maint', merge 'maint' to
+ 'master'; make sure that the result is what you want.
- - 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?)
+ $ git checkout master
+ $ git merge -m "Sync with 'maint'" --no-log maint
+ $ git log -p --first-parent ORIG_HEAD..
+ $ make test
- - Prepare 'jch' branch, which is used to represent somewhere
- between 'master' and 'seen' and often is slightly ahead of 'next'.
+ - Prepare to update the 'jch' branch, which is used to represent
+ somewhere between 'master' and 'seen' and often is slightly ahead
+ of 'next', and the 'seen' branch, which is used to hold the rest.
$ Meta/Reintegrate master..jch >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.
+ rebuild the current 'jch'. Do the same for 'seen'.
+
+ - Review the Meta/redo-jch.sh and Meta/redo-seen.sh scripts. The
+ former should have a line '### match next'---the idea is that
+ merging the topics listed before the line on top of 'master'
+ should result in a tree identical to that of 'next'.
- - 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:
+ - As newly created topics are usually merged near the tip of
+ 'seen', add them to the end of the Meta/redo-seen.sh script.
+ Among the topics that were in 'seen', there may be ones that
+ are not quite ready for 'next' but are getting there. Move
+ them from Meta/redo-seen.sh to the end of Meta/redo-jch.sh.
+ The expectation is that you'd use 'jch' as your daily driver
+ as the first guinea pig, so you should choose carefully.
+
+ - Now we are ready to start rebuilding 'jch' and 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
@@ -284,10 +304,12 @@ by doing the following:
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:
+ touch the line.
+
+ If a topic that was not in 'next' should be merged to 'next', add
+ it before the '### match next' line. Then:
- $ git checkout -B jch master
+ $ git checkout --detach master
$ sh Meta/redo-jch.sh -c1
to rebuild the 'jch' branch from scratch. "-c1" tells the script
@@ -299,26 +321,29 @@ by doing the following:
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'.
+ 'master', this time without using "-c1" to merge all topics.
- Then do the same to 'next'
+ 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.
+ be edited. The resulting tree should match 'jch^{/^### match next'}'
+ 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
+ If 'master' was updated before you started redoing 'next', then
- Then build the rest of 'jch':
+ $ git diff 'jch^{/^### match next}' next
- $ git checkout jch
- $ sh Meta/redo-jch.sh
+ would show differences that went into 'master' (which 'jch' has,
+ but 'next' does not yet---often it is updates to the release
+ notes). Merge 'master' back to 'next' if that is the case.
+
+ $ git merge -m "Sync with 'master'" --no-log master
When all is well, clean up the redo-jch.sh script with
@@ -328,12 +353,7 @@ by doing the following:
merged to 'master'. This may lose '### match next' marker;
add it again to the appropriate place when it happens.
- - Rebuild 'seen'.
-
- $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh
-
- Edit the result by adding new topics that are not still in 'seen'
- in the script. Then
+ - Rebuild 'seen' on top of 'jch'.
$ git checkout -B seen jch
$ sh Meta/redo-seen.sh
@@ -344,7 +364,7 @@ by doing the following:
Double check by running
- $ git branch --no-merged seen
+ $ git branch --no-merged seen '??/*'
to see there is no unexpected leftover topics.
--
2.46.0-rc1-48-g0900f1888e
