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

From: Nico Williams <[email-masked]>
Date: Mon, 14 Apr 2025 16:34:36 -0500

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.

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

> [1]: https://lore.kernel.org/git/[email-masked]/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
--