Subject: Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes

From: Junio C Hamano <[email-masked]>
Date: Tue, 01 Nov 2022 15:23:25 -0700

Jeff King <[email-masked]> writes:

> Why not have a single file with all of the topics, with two "###"
> markers?

Mostly because jch and seen are built in two distinct steps, and I
need to be able to rearrange lines in the redo-jch.sh file either in
the editor or by running "Meta/redo-jch.sh -u", without touching
what is in redo-seen.sh file (meaning: what comes after your final
"###" cut lines).

After replacing the existing topic branches and creating new ones
for new topics, decide which topics to merge down to master and next
and edit redo-jch.sh (while looking at the what's cooking report
and/or output from "Meta/cook -w").  If we merge some to 'master',
then tentatively write '###' marker before these topics.  Then

    $ git checkout --detach master
    $ Meta/redo-jch.sh -c1
    $ edit RelNotes
    $ git commit -a -s -m "${N}th batch"
    $ Meta/round -coccinelle ;# and other tests as necessary
    $ Meta/Reintegrate master.. >P
    $ git checkout master
    $ sh P && git commit --amend --no-edit --reset-author

will rebuild the 'master' (but this is needed only when 'master'
gets updated in the day's integration).  After that

    $ git checkout -B jch master
    $ Meta/redo-jch.sh

and use 

    $ git branch --no-merged jch --no-merged seen --sort=-committerdate '??/*'

to see any topics that are not in last 'seen' and 'jch' we just
rebuilt.  They are either replaced in 'seen' or new ones.  Then
merge some of them that you are more confident than others to 'jch'
and test and update the redo-jch.sh script.

    $ git merge xy/xxy
    $ git merge fr/otz
    ...
    $ Meta/round ;# or whatever tests that are appropriate
    $ Meta/redo-jch.sh -u

This "-u"pdate step can be done without disturbing what should later
build on top for 'seen' by having the script separately.  

When day's integration contains an update to 'next', there is
another step here:

    $ git checkout --detach next
    $ Meta/redo-jch.sh -c1
    $ git merge -m "Sync with 'master'" --no-log master
    $ Meta/round ;# or whatever tests that are appropriate
    $ git diff 'jch^{/^### match next}' ;# must be empty

After that, queue new topics that are more questionable on 'seen',
and the rest:

    $ git checkotu -B seen
    $ git merge ni/tfol
    $ git merge yo/min
    ...
    $ Meta/round ;# or whatever tests that are appropriate
    ... here, new topics may be worse than what I initially thought
    ... that they need to be ejected from 'seen'
    $ git reset --hard jch && git merge yo/min ... && Meta/round

And once satisfied with the new topics, queue the remainder.

    $ Meta/redo-seen.sh
    $ Meta/round ;# or whatever tests that are appropriate
    $ Meta/redo-seen.sh -u ;# finally

Being able to rebuild the redo-* script for only the 'jch' part,
independent from the 'seen' part, is quite essential in the
workflow, because I may not yet know how day's 'seen' would look
like, when I am recording the topics and integration order for 'jch'.