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

[Jeff King <peff@peff.net>]

On Mon, Oct 31, 2022 at 07:47:33PM -0400, Taylor Blau wrote:

> The documentation on how to use the scripts in 'todo' has a couple of
> small typos that make it confusing when generating the Meta/redo-jch.sh
> and Meta/redo-seen.sh scripts the first time.
> 
> Correct these to avoid any confusion in the future.

Thanks for writing these up. A little back-story: Taylor and I had
looked at this together off-list, because the results of following the
documentation to the letter made little sense.

So both look good to me, with the giant grain of salt that I was party
to the original head-scratching that led to the patches. Given that
there's no urgency (unless you are hit by a bus in the next few weeks),
it probably makes sense to queue these fixes and wait for Junio to
review and (hopefully) merge them.

There is one thing we wondered about, and I think only Junio can answer.
The instructions after these patches yield two files, redo-jch.sh and
redo-seen.sh. The first one has two sections separated by a "###"
marker: the ones that are in 'next', and the ones that are in 'jch'.
The third ones has topics that are only in 'seen' (which also contains
all of the others).

Why not have a single file with all of the topics, with two "###"
markers? I.e., something like:

  # build the topic list from what's in 'seen' now
  Meta/Reintegrate master..seen >Meta/redo.sh

  # rebuild the first part of jch, which is everything in next
  git checkout -B master jch
  Meta/redo.sh -c1

  # now build actual next, which should end up with the same tree
  git checkout next
  git merge master ;# if necessary
  Meta/redo.sh -c1 -e ;# -e to annotate any topics
  git diff jch next ;# should be identical

  # now build the rest of jch
  git checkout jch
  Meta/redo.sh -c2

  # now build seen
  git checkout -B seen master
  Meta/redo.sh ;# no -c, do it all

I _think_ the two are equivalent, and it seems more convenient to keep
all of the topic names in one file (since they'd migrate across the cut
to go from seen to jch, then jch to next). But maybe you (Junio) find it
more convenient to keep them separate. The 'seen' list is a bit more
fluid, and I'm sure you figured out how to copy lines between two
different buffers in emacs. :)

Mostly just curious.

-Peff