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

[Jeff King <peff@peff.net>]

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

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