Subject: Re: Why isn't 'jch' based on 'next'?

From: Junio C Hamano <[email-masked]>
Date: Thu, 15 Apr 2021 11:24:25 -0700

Denton Liu <[email-masked]> writes:

> Out of curiosity, why is 'jch' not based on 'next' but instead, it
> recreates the same merge commits on top of 'master'. What is the
> advantage of this?

The 'jch' point is merely a convenient "I personally have no problem
using this tree" point on 'seen', so I'll talk about 'seen'.

It is the second or third time I answer this exact question, and we
should add the answer to Documentation/howto/maintain-git.txt (or
MaintNotes on the todo branch), perhaps.

The history of 'next' can become quite messy due to many reasons:

 - A topic that has already been merged to 'next' but not graduated
   to 'master' may need some fix-up, in which case, 'next' will have
   another merge of the same topic into it.

 - A mismerge of a topic into 'next' may be discovered long after it
   happened, and a single-parent commit is made directly on 'next'
   to correct it.

 - When 'master' advances, it is merged back to 'next'.

 - A topic that looked promising may turn out to be a bad idea and
   the merge of the topic into 'next' get reverted out of 'next'.

 - A topic that looked nice may want to do a wholesale replacement,
   not an incremental refinement, and a merge of the topic into
   'next' get reverted and then the newer iteration of the topic
   gets merged to 'next' (this last case is rare, but it sometimes
   happens, like once every few cycles).

But we know which topic must be in 'next' all the time.  You can ask
'seen' which ones they are:

   $ git log --oneline --first-parent 'master..seen^{/^### match next}'

So if we reset 'seen' at 'master' and merge the tip of these topics
into it, the tree of the empty commit that is marked with "### match
next" marker should match the tree of 'next', or something is still
wrong (most likely, a mismerge).  Also, the order topics are merged
into 'next' may not be necessarily the order they appear in 'seen'.
Every time I rebuild 'seen' from 'master', I have a chance to reorder
these topics so that the ones that are expected to graduate sooner
come near the bottom.

By ensuring "### match next" and 'next' matches, even though they
came to their trees in different route, I can spot a mismerge that
is waiting to happen soon when a topic graduates to 'master'.