Re: [PATCH v7 01/10] Documentation/technical: add paint-down-to-common doc

From: Elijah Newren <newren@gmail.com>
Date: Aug 7, 2026, 03:00 UTC
Message-ID: <CABPp-BH2gfLOJdHJ3EqaRuCLkG=JNT=f_sO=7PTEgPqnppwYnA@mail.gmail.com>
In-Reply-To: <c1f303353caeb5be301ea24f4a042d695459061b.1786013982.git.gitgitgadget@gmail.com>

On Thu, Aug 6, 2026 at 4:04 AM Kristofer Karlsson via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 6 quoted lines

>
> From: Kristofer Karlsson <krka@spotify.com>
>
> Add a technical document describing the paint_down_to_common()
> algorithm used for merge-base computation, covering the paint
> walk, generation number regions, and termination conditions.

This is a great doc providing an overview of how everything works.

Show 8 quoted lines

> +With v1 commit-graphs (topological levels, no GDAT chunk),
> +generation numbers saturate at `GENERATION_NUMBER_V1_MAX`.
> +Saturated commits share the same generation value despite
> +different topological depths, which breaks ordering guarantees
> +in the same way as INFINITY. The early exit gates compare
> +against `GENERATION_NUMBER_V1_MAX` for v1 graphs and
> +`GENERATION_NUMBER_INFINITY` for v2 graphs, so that saturated
> +commits are treated as unordered.

Perfect, thanks for addressing this since the previous round.

Show 7 quoted lines

> +Generation cutoff
> +~~~~~~~~~~~~~~~~~
> +Some callers (notably `remove_redundant()`) supply a `min_generation`
> +threshold equal to the minimum generation of the input commits.
> +These callers only need to determine reachability among the inputs,
> +not find deep merge bases, so the walk can safely terminate when it
> +dequeues a commit below this threshold.

This reads much better; thanks.

The rest looks the same as the last round that I already reviewed and looks good.