Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document why 'seen' isn't based on 'next' #936

Open
Denton-L opened this issue Apr 20, 2021 · 3 comments
Open

Document why 'seen' isn't based on 'next' #936

Denton-L opened this issue Apr 20, 2021 · 3 comments

Comments

@Denton-L
Copy link
Member

https://lore.kernel.org/git/[email protected]/:

Denton Liu [email protected] 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'.

https://lore.kernel.org/git/[email protected]/:

Junio C Hamano [email protected] writes:

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.

This is so that I can "git checkout seen~40" (or whereever point
that has all the topics scheduled to be in 'master' and nothing
else) and run tests, to simulate what happens if these topics
graduate to 'master'.

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'.

@rimrul
Copy link

rimrul commented Jul 17, 2022

https://lore.kernel.org/git/[email protected]/

Stephen Smith writes:

Is there a reason that with the latest commits to the repository that next is
no longer an ancestor of seen and than main/master is no longer an ancestor
of next?

Let's get to the latter half of your question first.

Tips of various branches of Git project can be observed at
https://git.kernel.org/pub/scm/git/git.git/ and
https://github.com/git/git (among other mirrors) and they are at
these commits:

maint bbea4dc
master 9dd64cb
next 4dd4a11
seen c82b393

at the time of writing. The 'next' branch is designed to be always
a descendant of 'master', unless I screw up, and I'd appreciate if
you let me know when it happens. Right now, it is not the case,
though.

$ git rev-list --count 4dd4a11..9dd64cb
0

Now, the 'seen' branch never was, and will never be, a descendant of
'next'. It always is a decendant of 'master'.

Imagine how 'next' gets advanced. It will never rewind during a
release cycle, so it starts at a feature release, and merges topics
and also merges 'master' back. A topic might be merged once to
'next', then the topic may gain a commit or two to fix a bug in the
part of the topic that is already in 'next', and the updated topic
may be merged to 'next' again. IOW, some topics may have merged to
'next' in multiple steps. Topics cooking in 'next' may graduate by
getting merged to 'master', at which time, the draft release notes
is updated on the 'master' branch, and 'next' merges 'master' back.
This is to pick up the changes to the draft release notes. In other
words, the history graph of 'next' will be a mess.

The 'seen' branch serves three purposes.

  • The first is to allow sanity checking the result of messy merges
    into 'next'. For that, whenever 'master' advances, it is rebuilt
    from scratch from the tip of 'master' and merges each and every
    topic that are already in 'next' one by one, serially. Even
    topics that were merged in multiple steps to 'next' may be merged
    in full with a single merge to 'seen'. When all the topics in
    'next' (and nothing else) are merged, an empty single-parent
    commit with title '### match next' is added. The idea is that
    the tree of this commit should exactly match the tree of 'next',
    or there may be some mismerges. The 'next' branch, since it
    forked from the last release point, may have merged these topics
    in random order, in increments, and also merged back the changes
    made in 'master', but the end result should be the same as
    starting from the latest 'master' and merging the topics that are
    in 'next' but still not in 'master' one by one, each as a whole
    instead of doing so incrementally.

  • The second purpose of 'seen' is to gather other topics that I
    happened to have seen together into a single integration branch,
    so that

    (1) I can forewarn myself of possible conflicts and interactions
    among topics in flight, and

    (2) I can have a simple way to list all topics in flight.

    This is done by merging the other topic branches, on top of
    'seen^{/^### match next}' commit. To list the topics that I am
    juggling "git log --oneline --first-parent master..seen" is an
    effective way. For this to work, the rest of 'seen' cannot be
    built on top of 'next', whose history is allowed to be messy.
    This is why 'next' cannot be an ancestor of 'seen'.

  • The third purpose of 'seen' is to give me a version that I can be
    a guinea pig of. I have a build of "git" that is cut from a
    point in 'seen' that is used in my daily use.

@rahul3002
Copy link

i would like to take this issue

@dscho
Copy link
Member

dscho commented Sep 19, 2022

i would like to take this issue

No need to ask for permission ;-)

To get you started, you might want to have a look at https://gitgitgadget.github.io/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants