Re: [PATCH 2/2] doc/gitremote-helpers: match object-format option docs to code

From: Jeff King <peff@peff.net>
Date: Mar 12, 2024, 07:45 UTC
Message-ID: <20240312074513.GA47852@coredump.intra.peff.net>
In-Reply-To: <Zeo9oAkL6kxZRugN@tapette.crustytoothpaste.net>

On Thu, Mar 07, 2024 at 10:20:16PM +0000, brian m. carlson wrote:

Show 17 quoted lines

> > As I discussed in patch 1, remote-curl does handle the "true" thing
> > correctly. And that's really the helper that matters in practice (it's
> > possible some third party helper is looking for the explicit "true", but
> > presumably they'd have reported their confusion to the list). So we
> > could probably just start tacking on the "true" in transport-helper.c
> > and leave that part of the documentation untouched.
> > 
> > I'm less sure of the specific-algorithm thing, just because it seems
> > like remote-curl would never make use of it anyway (preferring instead
> > to match whatever algorithm is used by the http remote). But maybe there
> > are pending interoperability plans that depend on this?
> 
> It was designed to allow indicating that we know how to support both
> SHA-1 and SHA-256 and we want one or the other (so we don't need to do
> an expensive conversion).  However, if it's not implemented, I agree we
> should document what's implemented, and then extend it when interop
> comes.

I guess my reservation is that when it _does_ come time to extend, we'll have to introduce a new capability. The capability "object-format" has a documented meaning now, and what we send is currently a subset of that (sort of[1]). If we later start sending an explicit algorithm, then in theory they're supposed to handle that, too, if they implemented against the docs.

Whereas if we roll back the explicit-algorithm part of the docs, now we can't assume any helper claiming "object-format" will understand it. And we'll need them to say "object-format-extended" or something. That's both more work, and delays adoption for helpers which implemented what the current docs say.

So I guess my question was more of: are we thinking this explicit algorithm thing is coming very soon? If so, it might be worth keeping it in the docs. But if not, and it's just a hypothetical future, it may be better to clean things up now. And I ask you as the person who mostly juggles possible future algorithm plans in his head. ;) Of course if the answer is some combination of "I don't really remember what the plan was" and "I don't have time to work on it anytime soon" that's OK, too.

-Peff

[1] In the above I'm really just talking about the explicit-algorithm
    part. The "sort of" is that we claim to send "object-format true"
    but actually just send "object-format". There I'm more inclined to
    just align the docs with practice, as the two are equivalent.