GNU bug report logs - #53368
.guix-authorizations 'version' field documentation

Previous Next

Full log

Message #11 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: .guix-authorizations 'version' field documentation
Date: Thu, 20 Jan 2022 14:07:50 +0100

[Message part 1 (text/plain, inline)]

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.

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.