Re: [PATCH v7 08/10] commit-reach: terminate merge-base walk when one paint side is exhausted

On Fri, 7 Aug 2026 at 05:02, Elijah Newren <[email protected]> wrote:
>
> > The INFINITY gate ensures correctness: commits without a commit-graph
> > entry have GENERATION_NUMBER_INFINITY and are ordered by commit date,
> > which is not topologically reliable. The optimization only fires
> > once the walk enters the finite-generation region where ordering
> > guarantees hold.
>
> What about GENERATION_NUMBER_V1_MAX ?

I am planning to rewrite the documentation to refer to the regions
as (topologically) ordered vs unordered (I think you coined it in
one of the other emails, and I quite prefer that over
infinite/finite).

I guess I will need to rewrite the commit messages too, to reflect
that. Hopefully fixed with v8, unless I miss something in that
juggling.

> > +  5. Side exhaustion: no pure PARENT1 or pure PARENT2 commits
> > +     remain in the queue, no pending merge-base candidates exist,
> > +     and the walk has entered the finite-generation region.
>
> "finite" or "small enough" ?

I think finite was correct before, given that the alternative was
the infinite region (GENERATION_NUMBER_INFINITE) but I will
rephrase this as unordered and ordered for v8.

> "In the INFINITY region" -> "outside the reliably-ordered region" ?

Agreed, I will pick something along those lines at the very least
(maybe exactly, but no promise yet).

> At this point in the series,
> Documentation/technical/paint-down-to-common.adoc does point out the
> GENERATION_NUMBER_V1_MAX issue in one of the paragraphs; it's kind of
> glossed over in other later paragraphs (as I highlighted above), but
> there's a clear incongruence at this point in the series.  I'm
> guessing you're going to fix that up in the next two patches, but the
> splitting feels a bit off.

V1_MAX is introduced before it's referenced in code, though I think
it's still valid as a concept for the existing docs, I just need
to be careful how I frame it in terms of the implementation.

I will do something here, though I am not yet sure exactly what.

Thanks,
Kristofer