On Fri, Jun 27, 2025 at 8:48 PM Jean-Noël Avila <jn.avila@xxxxxxx> wrote: > > Le 25/06/2025 à 14:50, Christian Couder a écrit : > > +promisor.sendFields:: > > + A comma or space separated list of additional remote related > > + field names. A server will send these field names and the > > + associated field values from its configuration when > > + advertising its promisor remotes using the "promisor-remote" > > + capability, see linkgit:gitprotocol-v2[5]. Currently, only the > > + "partialCloneFilter" and "token" field names are supported. > > ++ > > +* "partialCloneFilter": contains the partial clone filter > > + used for the remote. > > ++ > > +* "token": contains an authentication token for the remote. > > ++ > > This kind of text structure calls a description list instead and you can > already use backquotes: > > `partialCloneFilter`:: contains the partial clone filter > > + used for the remote. > > ++ > > +`token`:: contains an authentication token for the remote. Thanks for the suggestion. I have used that in v6. > > +When a field name is part of this list and a corresponding > > +"remote.foo.<field name>" config variable is set on the server to a > > Please no space in placeholders: <field-name> > > > +non-empty value, then the field name and value will be sent when > > +advertising the promisor remote "foo". > > ++ > > +This list has no effect unless the "promisor.advertise" config > > +variable is set to "true", and the "name" and "url" fields are always > > +advertised regardless of this setting. > > + > > More generally, I am a bit annoyed by the usage of the "will" auxiliary > when not expressing a true future. For an international audience, this > can be misleading. The plain language[1] philosophy mandates to not use > auxiliaries other than where they are required (no convoluted sentences). I have removed some usage of "will" in the patches in v6. I haven't changed the existing documentation in this file though. > Would it make sense to start a style guide to help writing consistent > documentation that targets people whose first language is not English? > Being an non native speaker, I often find our docs too literate, with > lengthy sentences. > > [1] https://en.wikipedia.org/wiki/Plain_language I think it's a separate discussion, and I am not sure I want to participate in it. > > promisor.acceptFromServer:: > > If set to "all", a client will accept all the promisor remotes > > a server might advertise using the "promisor-remote" > > diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc > > index 9a57005d77..0583fafa09 100644 > > --- a/Documentation/gitprotocol-v2.adoc > > +++ b/Documentation/gitprotocol-v2.adoc > > @@ -785,33 +785,59 @@ retrieving the header from a bundle at the indicated URI, and thus > > save themselves and the server(s) the request(s) needed to inspect the > > headers of that bundle or bundles. > > > > -promisor-remote=<pr-infos> > > +promisor-remote=<pr-info> > > ~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Be careful to adjust the length of the underline to the one of the title I have adjusted it in v6. Thanks. [...] > > +After these mandatory fields, the server MAY advertise the following > > +optional fields in any order: > > + > > +- "partialCloneFilter": The filter specification used by the remote. > > +Clients can use this to determine if the remote's filtering strategy > > +is compatible with their needs (e.g., checking if both use "blob:none"). > > +It corresponds to the "remote.<name>.partialCloneFilter" config setting. > > + > > +- "token": An authentication token that clients can use when > > +connecting to the remote. It corresponds to the "remote.<name>.token" > > +config setting. > > + > > This list can be turned into a description list. Done. > > +No other fields are defined by the protocol at this time. Clients MUST > > +ignore fields they don't recognize to allow for future protocol > > +extensions. > > + > > +For now, the client can only use information transmitted through these > > +fields to decide if it accepts the advertised promisor remote. In the > > +future that information might be used for other purposes though. > > + > > +Field values MUST be urlencoded. > > + > > +If the client decides to use one or more promisor remotes the server > > +advertised, it can reply with "promisor-remote=<pr-names>" where > > +<pr-names> should be of the form: > > + > > + pr-names = pr-name | pr-names ";" pr-names > > Here the syntax used is not compatible with synopsis. Would it make > sense to uniformize it, or is BNF ok? I am not sure what you call the "synopsis". Is it "promisor-remote=<pr-info>"? If yes, then I think "promisor-remote=<pr-names>" where pr-names = pr-name | pr-names ";" pr-name (which is what I have currently) should be considered compatible. Or do you have another suggestion? Thanks for your review, Christian.
