bug#53368: .guix-authorizations 'version' field documentation

[Maxime Devos <maximedevos@telenet.be>]

[-- Attachment #1: Type: text/plain, Size: 1635 bytes --]

Hi,

Christopher Rodriguez schreef op wo 19-01-2022 om 09:40 [-0500]:
> Hey all,
> 
> I've just been able to clone my authenticated personal repository for
> the first time in a few weeks because I was confusing the `version`
> field of `(authorizations …` to be a file version field as opposed to
> the version of the API being used.
> 
> For clarity, I'm working on a patch that will edit the section of the
> manual to clearly specify that this is the API version (will submit
> soon). It currently has a comment in the example source that reads
> "current file format version", which lead me to this mistake. Nowhere
> else in the text is the `version` field mentioned.
> 
> However, as a Lisper, I feel as though the symbol itself could easily
> be more descriptive by using `api-version` or something similar rather
> than just a generic `version`. It would help prevent other newcomers
> from going through the confusion I've just had.
> 
> What do You think?

'version' does denote a file format version.  Calling it an API version
is somewhat inaccurate, because it is not a application _programming_
interface -- you can't write Scheme code in .guix-authorizations,
only S-exps that match the file format.

While it is the version of the file format, it is not the version of
the file, which I believe is were the confusion came from?

Also, changing 'version' to 'api-version' would probably prevent old
versions of Guix (that only recognise 'version') from pulling new
versions of Guix (that would have an 'api-version' in their
.guix-authorizations) (untested).

Greetings,
Maxime.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]