Re: Semantics of change IDs (Re: Gerrit, GitButler, and Jujutsu projects collaborating on change-id commit footer)

From: Nico Williams <nico@cryptonector.com>
Date: Apr 14, 2025, 21:34 UTC
Message-ID: <Z/1/bDQnWc8Lj29S@ubby>
In-Reply-To: <CALnO6CC_Gvqhcxp4AknwM+YSsngv_0zngKb2XHXN4u0AvKEMMg@mail.gmail.com>

On Mon, Apr 14, 2025 at 03:54:23PM -0400, D. Ben Knoble wrote:

> Using URIs [to code reviews] looks to me like it makes some
> assumptions about what creates or consumes these headers, right?
> Especially since the URI should point to a code review… Is there a way
> to do that which is downstream-agnostic?

You could tag the URI(s) with purposes, but URIs are already pretty agnostic as to what is being referenced by them as they are merely the reference. That said, if you need to decompose the URI into specific subitems then you need to understand the underlying application's local-part (and q-param, if any) scheme.

> Further, and maybe this is my ignorance of Gerrit showing: how would
> you attach a URI to a local commit when authoring it? You don't have
> the review URI when running `git commit`, do you? (Maybe I
> misunderstood; I'm seeing an odd chicken-egg problem here.)

Excellent outlook-changing question. Local tooling would be needed, which would be annoying if that tooling were not Git itself, but if it's Git then how would it interface with Gerrit or any other such tools? We'd have to define APIs for that, and that too would be annoying. So it has to be `git commit` (or `git rebase -i` and then use a new verb to stop and set a commit's change ID metadata, like `reword`, but for metadata), which means the user has to acquire a CR before creating the CR, so the CR tools would have to support that.

On the other hand if it's not CR URIs but more like ticket URIs (as in JIRA, bugzilla, etc.) then it's much easier.

People already use ticket IDs all the time, typically in the commit subject, else in the commit commentary, typically using some specific form. For example Illumos has devs put one ticket ID in the subject and if there are more ticket IDs then the body of the commit message must start with each additional ticket ID on a line by itself with the ticket's synopsis following the ID. E.g., https://src.illumos.org/source/history/illumos-gate/ (I think they don't allow any actual commentary in the commit message body, with all commentary having to be in the tickets).

Typically tickets have to exist before the commits get created, and in cases like Illumos' tickets have to exist before the code review is created, and the commits have to reference the relevant ticket(s).

OTOH in the Illumos case you see that in a CR one might have multiple commits for different tickets each, and still all be related. A change ID/URI could be used to link those together without having to go spelunking in the ticket system. Also ticket IDs (and URIs) could be handy as a header in the commits because otherwise one has to know the commit naming conventions of the project. Illumos, for example, could link tickets by ID in the subject and commit message body and by URI in commit headers (or footers).

> Which begs another question: what/who applies the initial change ID to
> a commit and when?

See above.

> I've skimmed most of the discussion, and I think a unique ID for an
> in-flight series could be useful for ergonomics and to support more
> tools that link between versions of the series.

Also to ease back- and forward-ports. Though to be fair that's a mostly solved probalm as when users do those typically they start with a ticket, find a CR linked from the ticket, find the corresponding commits in the main branch, then go from there. A change ID might not be more helpful than that. Then again, if you're doing a second or third backport then one could find earlier backports that might be easier to port from than the main branch commits, and here then a change ID might help.

> Re-reading the original post [1] (which didn't mention this kind of
> ID?), I'm having a hard time seeing the problem statement. [...]

It mentions a "change ID". I'm supposing it could be a URI, but I don't care if it's not, and if it's easier then ignore the URI thing.

Show 5 quoted lines

> It looks to me, an outsider, like the problem is some combination of
> "I want to track a commit's evolution" and "I want to see related
> commits in review, esp. when it's an identical and already-approved
> commit." But I might be misreading, and clarifying the problem
> statement might help bring us to a better core solution?

I'm the one introducing the second of those, and perhaps I should butt off.

Show 11 quoted lines

> [1]: https://lore.kernel.org/git/xmqqh62tm5fo.fsf@gitster.g/T/#m038be849b9b4020c16c562d810cf77bad91a2c87
> 
> Cheers,
> D. Ben Knoble
> 
> PS This discussion feels somewhat related to the classic GitHub
> problem of not presenting interdiffs/range-diffs: GitHub shows a
> too-flat source diff on force-pushes. Perhaps better web UI tooling
> about interdiff review (which I think is one of the things Gerrit
> does/wants to do?) makes change IDs less necessary, since interdiffs
> help connect evolutions of commits?

Nothing here could force GH to make their UI nicer and more featureful.

Nico