Re: [PATCH 06/13] docs: indicate new credential protocol fields

[M Hickford <mirth.hickford@gmail.com>]

On Mon, 25 Mar 2024 at 23:37, brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2024-03-25 at 23:16:09, M Hickford wrote:
> > > +`authtype`::
> > > +   This indicates that the authentication scheme in question should be used.
> > > +   Common values for HTTP and HTTPS include `basic`, `digest`, and `ntlm`,
> > > +   although the latter two are insecure and should not be used.  If `credential`
> > > +   is used, this may be set to an arbitrary string suitable for the protocol in
> > > +   question (usually HTTP).
> >
> > How about adding 'bearer' to this list? Popular hosts Bitbucket
> > https://bitbucket.org and Gitea/Forgejo (such as https://codeberg.org)
> > support Bearer auth with OAuth tokens.
>
> Sure, I can do that.
>
> > > ++
> > > +This value should not be sent unless the appropriate capability (see below) is
> > > +provided on input.
> > > +
> > > +`credential`::
> > > +   The pre-encoded credential, suitable for the protocol in question (usually
> > > +   HTTP).  If this key is sent, `authtype` is mandatory, and `username` and
> > > +   `password` are not used.
> >
> > A credential protocol attribute named 'credential' is confusing. How
> > about 'authorization' since it determines the HTTP Authorization
> > header? This detail is surely worth mentioning too.

Would it be accurate to add "For HTTP, Git concatenates the authtype
and credential attributes to determine the Authorization header"?

>
> I don't want this to be very specific to HTTP, so I don't think that's a
> great name.  As I mentioned in the cover letter, I might well extend
> this to IMAP and SMTP for our mail handling in the future, and that name
> wouldn't work well there.

Good point, you've dissuaded me against 'authorization'.

>
> I named it `credential` because, well, it's the credential that's used
> in the protocol.  I feel like saying that the field represents "the
> authorization" sounds unnatural.  It's not wrong, per se, but it sounds
> confusing.

We already use 'credential' to describe the whole collection of
attributes, as in "The credential is split into a set of named
attributes".

>
> I'm open to other ideas if you or others have them, but between these
> two, I think I'd prefer to stick with `credential`.

Ideas anyone?


> --
> brian m. carlson (they/them or he/him)
> Toronto, Ontario, CA