New CLI syntax for package version

New CLI syntax for package version

[Ludovic Courtès]

In <http://bugs.gnu.org/19219>, we came to the conclusion that we need a
new syntax to denote a specific package version on the command line.

The current syntax is described in the manual (info "(guix) Invoking
guix package").  Basically, ‘guile-1.8’ refers to version 1.8.x of
Guile; however, this syntax has proved to be ambiguous for packages
whose name contains digits.

For the new syntax, the proposals so far are:

  1. slash, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#25>

     guile:1.8/doc
     xterm-256-color:320
     emacs:24.5/out

  2. underscore, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#28>

     emacs_24.5:out

  3. at, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#31>

     guile@1.8
     guile@1.8:doc

What do people think?

Ludo’.

Re: New CLI syntax for package version

[Andreas Enge]

On Sat, Jan 09, 2016 at 10:26:22PM +0100, Ludovic Courtès wrote:
>   2. underscore, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#28>
>      emacs_24.5:out

I do not like this one, as the "_" is not sufficiently "separating" - it
looks too much like "-", which can be part of a package name. The other
two would work well.

Andreas

Re: New CLI syntax for package version

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> In <http://bugs.gnu.org/19219>, we came to the conclusion that we need a
> new syntax to denote a specific package version on the command line.
>
> The current syntax is described in the manual (info "(guix) Invoking
> guix package").  Basically, ‘guile-1.8’ refers to version 1.8.x of
> Guile; however, this syntax has proved to be ambiguous for packages
> whose name contains digits.
>
> For the new syntax, the proposals so far are:
>
>   1. slash, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#25>
>
>      guile:1.8/doc
>      xterm-256-color:320
>      emacs:24.5/out

That’s really “colon”, rather than “slash”.  The slash is used to
separate the output, which reminds me of paths.

>   2. underscore, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#28>
>
>      emacs_24.5:out

I do not like this one.

>   3. at, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#31>
>
>      guile@1.8
>      guile@1.8:doc

I like the “@” because it reads as “guile at [version] 1.8”.  A colon to
separate the output name from the rest works just as well as a slash
(proposed above); I have no preference here.

~~ Ricardo

Re: New CLI syntax for package version

[Christopher Allan Webber]

Ricardo Wurmus writes:

>>   2. underscore, <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#28>
>>
>>      emacs_24.5:out
>
> I do not like this one.

Just joining in the chorus, the underscore one really bothers me.

The other options seem fine!

Re: New CLI syntax for package version

[Eric Bavier]

On 2016-01-10 21:37, Christopher Allan Webber wrote:
> Ricardo Wurmus writes:
> 
>>>   2. underscore, 
>>> <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19219#28>
>>> 
>>>      emacs_24.5:out
>> 
>> I do not like this one.
> 
> Just joining in the chorus, the underscore one really bothers me.
> 
> The other options seem fine!

Same here.

-- 
`~Eric

Re: New CLI syntax for package version

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> In <http://bugs.gnu.org/19219>, we came to the conclusion that we need a
> new syntax to denote a specific package version on the command line.
>
> The current syntax is described in the manual (info "(guix) Invoking
> guix package").  Basically, ‘guile-1.8’ refers to version 1.8.x of
> Guile; however, this syntax has proved to be ambiguous for packages
> whose name contains digits.

Should we also take some time to reconsider how we name unreleased
versions like arbitrary git commits?

So far we have been picking the latest release version (or “0.0.0” if
there hasn’t been any release) followed by “.” and either a date or a
guix-internal revision number, then again a “.” followed by part of the
commit hash.

I’m afraid that we might accidentally introduce conflicts with future
release versions, e.g. when the latest release only uses two digits
(e.g. “0.1”) and we add a revision or a date (e.g. “0.1.1” or
“0.1.20160112”) and the next release and the next official release
switches to three digits (e.g. “0.1.1”).

Would it make sense to separate our version identifier from the actual
release version with a different character than “.”?  Or should this be
discussed elsewhere as it hasn’t anything to do with how we specify
versions on the command line?

~~ Ricardo

Version numbers for VCS snapshots

[Ludovic Courtès]

Ricardo Wurmus <rekado@elephly.net> skribis:

> Should we also take some time to reconsider how we name unreleased
> versions like arbitrary git commits?

Let do that!

> So far we have been picking the latest release version (or “0.0.0” if
> there hasn’t been any release) followed by “.” and either a date or a
> guix-internal revision number, then again a “.” followed by part of the
> commit hash.
>
> I’m afraid that we might accidentally introduce conflicts with future
> release versions, e.g. when the latest release only uses two digits
> (e.g. “0.1”) and we add a revision or a date (e.g. “0.1.1” or
> “0.1.20160112”) and the next release and the next official release
> switches to three digits (e.g. “0.1.1”).
>
> Would it make sense to separate our version identifier from the actual
> release version with a different character than “.”?  Or should this be
> discussed elsewhere as it hasn’t anything to do with how we specify
> versions on the command line?

Probably.  Debian, for instance, uses “2.0.11-9” where “9” denotes the
9th package revision of upstream version “2.0.11”.  We could probably
use that convention.

In a previous discussion on this topic, I suggested that we should have
such a revision number instead of just “x.y.COMMIT”.  The extra
monotonically-increasing revision number is needed to allow upgrades to
work as expected.

So, a Git snapshot’s version number could be:

  2.0.11-3.deadbeef
    ^    ^    ^
    |    |    `— upstream commit ID
    |    |
    |    `—— 3rd Guix package revision
    |    
  latest upstream version

The next snapshot would be:

  2.0.11-4.cafeefac

WDYT?

Ludo’.

Re: Version numbers for VCS snapshots

[Ben Woodcroft]

On 12/01/16 19:26, Ludovic Courtès wrote:
> Ricardo Wurmus <rekado@elephly.net> skribis:
>
>> Should we also take some time to reconsider how we name unreleased
>> versions like arbitrary git commits?
> Let do that!
Lets.
>> So far we have been picking the latest release version (or “0.0.0” if
>> there hasn’t been any release) followed by “.” and either a date or a
>> guix-internal revision number, then again a “.” followed by part of the
>> commit hash.
>>
>> I’m afraid that we might accidentally introduce conflicts with future
>> release versions, e.g. when the latest release only uses two digits
>> (e.g. “0.1”) and we add a revision or a date (e.g. “0.1.1” or
>> “0.1.20160112”) and the next release and the next official release
>> switches to three digits (e.g. “0.1.1”).
>>
>> Would it make sense to separate our version identifier from the actual
>> release version with a different character than “.”?  Or should this be
>> discussed elsewhere as it hasn’t anything to do with how we specify
>> versions on the command line?
> Probably.  Debian, for instance, uses “2.0.11-9” where “9” denotes the
> 9th package revision of upstream version “2.0.11”.  We could probably
> use that convention.
>
> In a previous discussion on this topic, I suggested that we should have
> such a revision number instead of just “x.y.COMMIT”.  The extra
> monotonically-increasing revision number is needed to allow upgrades to
> work as expected.
>
> So, a Git snapshot’s version number could be:
>
>    2.0.11-3.deadbeef
>      ^    ^    ^
>      |    |    `— upstream commit ID
>      |    |
>      |    `—— 3rd Guix package revision
>      |
>    latest upstream version
>
> The next snapshot would be:
>
>    2.0.11-4.cafeefac
>
> WDYT?
I can't see anything wrong with this myself. Is this accepted policy now?

Also, is the convention for unreleased software to take 0.0.0 as the 
version as you suggest Ricardo e.g. 0.0.0-1.deadbeef ?

ta
ben

Re: Version numbers for VCS snapshots

[Leo Famulari]

On Thu, Jan 21, 2016 at 02:51:29PM +1000, Ben Woodcroft wrote:
> 
> 
> On 12/01/16 19:26, Ludovic Courtès wrote:
> >Ricardo Wurmus <rekado@elephly.net> skribis:
> >
> >>Should we also take some time to reconsider how we name unreleased
> >>versions like arbitrary git commits?
> >Let do that!
> Lets.
> >>So far we have been picking the latest release version (or “0.0.0” if
> >>there hasn’t been any release) followed by “.” and either a date or a
> >>guix-internal revision number, then again a “.” followed by part of the
> >>commit hash.
> >>
> >>I’m afraid that we might accidentally introduce conflicts with future
> >>release versions, e.g. when the latest release only uses two digits
> >>(e.g. “0.1”) and we add a revision or a date (e.g. “0.1.1” or
> >>“0.1.20160112”) and the next release and the next official release
> >>switches to three digits (e.g. “0.1.1”).
> >>
> >>Would it make sense to separate our version identifier from the actual
> >>release version with a different character than “.”?  Or should this be
> >>discussed elsewhere as it hasn’t anything to do with how we specify
> >>versions on the command line?
> >Probably.  Debian, for instance, uses “2.0.11-9” where “9” denotes the
> >9th package revision of upstream version “2.0.11”.  We could probably
> >use that convention.
> >
> >In a previous discussion on this topic, I suggested that we should have
> >such a revision number instead of just “x.y.COMMIT”.  The extra
> >monotonically-increasing revision number is needed to allow upgrades to
> >work as expected.
> >
> >So, a Git snapshot’s version number could be:
> >
> >   2.0.11-3.deadbeef
> >     ^    ^    ^
> >     |    |    `— upstream commit ID
> >     |    |
> >     |    `—— 3rd Guix package revision
> >     |
> >   latest upstream version
> >
> >The next snapshot would be:
> >
> >   2.0.11-4.cafeefac
> >
> >WDYT?
> I can't see anything wrong with this myself. Is this accepted policy now?
> 
> Also, is the convention for unreleased software to take 0.0.0 as the version
> as you suggest Ricardo e.g. 0.0.0-1.deadbeef ?

That sounds good to me. There was some discussion of how much of the
hash to keep here:
http://lists.gnu.org/archive/html/guix-devel/2015-12/msg00136.html

I like this method that I've seen in some of the packages, because it
keeps the version tidy while preserving the full hash:

--8<---------------cut here---------------start------------->8---
(define-public hello
  (let ((commit "e8e46123cfe62170a2f7f79db6b471b66ae36947"))
    (package
      (name "hello")
      (version (string-append "2.10-1" (string-take commit 8)))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                       (url "git://git.sv.gnu.org/hello.git")
                       (commit commit)))
                (sha256
                [...]
--8<---------------cut here---------------end--------------->8---

> 
> ta
> ben
> 

Re: Version numbers for VCS snapshots

[Ricardo Wurmus]

Leo Famulari <leo@famulari.name> writes:

> That sounds good to me. There was some discussion of how much of the
> hash to keep here:
> http://lists.gnu.org/archive/html/guix-devel/2015-12/msg00136.html
>
> I like this method that I've seen in some of the packages, because it
> keeps the version tidy while preserving the full hash:
>
> --8<---------------cut here---------------start------------->8---
> (define-public hello
>   (let ((commit "e8e46123cfe62170a2f7f79db6b471b66ae36947"))
>     (package
>       (name "hello")
>       (version (string-append "2.10-1" (string-take commit 8)))
>       (source (origin
>                 (method git-fetch)
>                 (uri (git-reference
>                        (url "git://git.sv.gnu.org/hello.git")
>                        (commit commit)))
>                 (sha256
>                 [...]
> --8<---------------cut here---------------end--------------->8---

I like this approach (though I’ve been taking 9 characters of the commit
;)).

~~ Ricardo

Re: Version numbers for VCS snapshots

[Ricardo Wurmus]

Ben Woodcroft <b.woodcroft@uq.edu.au> writes:

> On 12/01/16 19:26, Ludovic Courtès wrote:
>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>
>>> Would it make sense to separate our version identifier from the actual
>>> release version with a different character than “.”?  Or should this be
>>> discussed elsewhere as it hasn’t anything to do with how we specify
>>> versions on the command line?
>> Probably.  Debian, for instance, uses “2.0.11-9” where “9” denotes the
>> 9th package revision of upstream version “2.0.11”.  We could probably
>> use that convention.
>>
>> In a previous discussion on this topic, I suggested that we should have
>> such a revision number instead of just “x.y.COMMIT”.  The extra
>> monotonically-increasing revision number is needed to allow upgrades to
>> work as expected.
>>
>> So, a Git snapshot’s version number could be:
>>
>>    2.0.11-3.deadbeef
>>      ^    ^    ^
>>      |    |    `— upstream commit ID
>>      |    |
>>      |    `—— 3rd Guix package revision
>>      |
>>    latest upstream version
>>
>> The next snapshot would be:
>>
>>    2.0.11-4.cafeefac
>>
>> WDYT?
> I can't see anything wrong with this myself. Is this accepted policy now?

I think this is a good policy to follow.  So far we didn’t always use
“-” to separate the upstream version from the revision + commit ID (or
did only I do this wrong?).  Some packages use “.”, which is what
prompted me to ask for clarification.

> Also, is the convention for unreleased software to take 0.0.0 as the 
> version as you suggest Ricardo e.g. 0.0.0-1.deadbeef ?

I think this is reasonable.  It’s rather unusual for software to be
released as “0.0.0”, so I don’t think we need to worry about this.  Even
then we could just update the Guix package revision number to force an
update.

~~ Ricardo

Re: Version numbers for VCS snapshots

[Leo Famulari]

On Thu, Jan 21, 2016 at 10:40:41AM +0100, Ricardo Wurmus wrote:
> 
> Leo Famulari <leo@famulari.name> writes:
> 
> > That sounds good to me. There was some discussion of how much of the
> > hash to keep here:
> > http://lists.gnu.org/archive/html/guix-devel/2015-12/msg00136.html
> >
> > I like this method that I've seen in some of the packages, because it
> > keeps the version tidy while preserving the full hash:
> >
> > --8<---------------cut here---------------start------------->8---
> > (define-public hello
> >   (let ((commit "e8e46123cfe62170a2f7f79db6b471b66ae36947"))
> >     (package
> >       (name "hello")
> >       (version (string-append "2.10-1" (string-take commit 8)))
> >       (source (origin
> >                 (method git-fetch)
> >                 (uri (git-reference
> >                        (url "git://git.sv.gnu.org/hello.git")
> >                        (commit commit)))
> >                 (sha256
> >                 [...]
> > --8<---------------cut here---------------end--------------->8---
> 
> I like this approach (though I’ve been taking 9 characters of the commit
> ;)).

I like 10 but I wanted to match your example upthread ;) It doesn't
matter so much if you preserve the full hash as in this case; you can
always add more characters later.

> 
> ~~ Ricardo

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

Leo Famulari <leo@famulari.name> skribis:

> On Thu, Jan 21, 2016 at 10:40:41AM +0100, Ricardo Wurmus wrote:
>> 
>> Leo Famulari <leo@famulari.name> writes:
>> 
>> > That sounds good to me. There was some discussion of how much of the
>> > hash to keep here:
>> > http://lists.gnu.org/archive/html/guix-devel/2015-12/msg00136.html
>> >
>> > I like this method that I've seen in some of the packages, because it
>> > keeps the version tidy while preserving the full hash:
>> >
>> > --8<---------------cut here---------------start------------->8---
>> > (define-public hello
>> >   (let ((commit "e8e46123cfe62170a2f7f79db6b471b66ae36947"))
>> >     (package
>> >       (name "hello")
>> >       (version (string-append "2.10-1" (string-take commit 8)))
>> >       (source (origin
>> >                 (method git-fetch)
>> >                 (uri (git-reference
>> >                        (url "git://git.sv.gnu.org/hello.git")
>> >                        (commit commit)))
>> >                 (sha256
>> >                 [...]
>> > --8<---------------cut here---------------end--------------->8---
>> 
>> I like this approach (though I’ve been taking 9 characters of the commit
>> ;)).
>
> I like 10 but I wanted to match your example upthread ;)

I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.

Ludo’.

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

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

Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:

> Ben Woodcroft <b.woodcroft@uq.edu.au> writes:
>
>> On 12/01/16 19:26, Ludovic Courtès wrote:

[...]

>>> So, a Git snapshot’s version number could be:
>>>
>>>    2.0.11-3.deadbeef
>>>      ^    ^    ^
>>>      |    |    `— upstream commit ID
>>>      |    |
>>>      |    `—— 3rd Guix package revision
>>>      |
>>>    latest upstream version
>>>
>>> The next snapshot would be:
>>>
>>>    2.0.11-4.cafeefac
>>>
>>> WDYT?
>> I can't see anything wrong with this myself. Is this accepted policy now?
>
> I think this is a good policy to follow.  So far we didn’t always use
> “-” to separate the upstream version from the revision + commit ID (or
> did only I do this wrong?).  Some packages use “.”, which is what
> prompted me to ask for clarification.

If there are no objections, I’ll commit the attached patch, which will
make it Official Policy.

Thoughts?

Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1564 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index a5816e9..f3520c2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -10130,6 +10130,36 @@ If we also wanted GTK+ 3.8.2, this would be packaged as
     ...))
 @end example
 
+@cindex version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases.  This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is.  Yet, it is sometimes necessary.  So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer.  Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot.  The resulting version string looks like this:
+
+@example
+2.0.11-3.deadbeef
+  ^    ^    ^
+  |    |    `-- upstream commit ID
+  |    |
+  |    `--- Guix package revision
+  |
+latest upstream version
+@end example
+
+It is a good idea to strip commit identifiers to, say, 7 digits so that
+they do not become aesthetically disturbing (assuming aesthetics have a
+role to play here.)  It is best to use the full commit identifiers in
+@code{origin}s, though, to avoid ambiguities.
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions
 

Re: Version numbers for VCS snapshots

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> +
> +It is a good idea to strip commit identifiers to, say, 7 digits so that
> +they do not become aesthetically disturbing (assuming aesthetics have a
> +role to play here.)  It is best to use the full commit identifiers in
> +@code{origin}s, though, to avoid ambiguities.
> +

I would probably find this a little confusing if I didn’t already know
what you meant.  Where should commit identifiers be stripped?  Are there
more places than just the ‘version’ field?  Could we name the ‘version’
field as an example?

Is it only aesthetics or also a matter of keeping shebangs shorter (in
case the output provides an interpreter that could end up in a shebang
line).  The version is usually part of the output name, so maybe it
would make sense to mention the ‘version’ field explicitly.

~~ Ricardo

Re: Version numbers for VCS snapshots

[Eric Bavier]

On 2016-01-21 15:25, ludo@gnu.org wrote:
> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
> 
>> Ben Woodcroft <b.woodcroft@uq.edu.au> writes:
>> 
>>> On 12/01/16 19:26, Ludovic Courtès wrote:
> 
> [...]
> 
>>>> So, a Git snapshot’s version number could be:
>>>> 
>>>>    2.0.11-3.deadbeef
>>>>      ^    ^    ^
>>>>      |    |    `— upstream commit ID
>>>>      |    |
>>>>      |    `—— 3rd Guix package revision
>>>>      |
>>>>    latest upstream version
>>>> 
>>>> The next snapshot would be:
>>>> 
>>>>    2.0.11-4.cafeefac
>>>> 
>>>> WDYT?
>>> I can't see anything wrong with this myself. Is this accepted policy 
>>> now?
>> 
>> I think this is a good policy to follow.  So far we didn’t always use
>> “-” to separate the upstream version from the revision + commit ID (or
>> did only I do this wrong?).  Some packages use “.”, which is what
>> prompted me to ask for clarification.
> 
> If there are no objections, I’ll commit the attached patch, which will
> make it Official Policy.
> 
> Thoughts?

My only issue with the attached patch is that the commit identifier in 
the example is not 7 digits (characters?) as recommended.

-- 
`~Eric

Re: Version numbers for VCS snapshots

[Jookia]

On Thu, Jan 21, 2016 at 04:08:24PM -0600, Eric Bavier wrote:
> On 2016-01-21 15:25, ludo@gnu.org wrote:
>
> My only issue with the attached patch is that the commit identifier in the
> example is not 7 digits (characters?) as recommended.

Maybe it'd be better to just round it up to 8 and keep the example? :)

Jookia.

Re: Version numbers for VCS snapshots

[Andy Wingo]

On Thu 21 Jan 2016 22:25, ludo@gnu.org (Ludovic Courtès) writes:

> +2.0.11-3.deadbeef

I thought you were vegetarian :)  2.0.11-3.cabba9e has 7 digits.

Andy, clearly providing very key and crucial feedback

Re: Version numbers for VCS snapshots

[Ricardo Wurmus]

Andy Wingo <wingo@igalia.com> writes:

> On Thu 21 Jan 2016 22:25, ludo@gnu.org (Ludovic Courtès) writes:
>
>> +2.0.11-3.deadbeef
>
> I thought you were vegetarian :)  2.0.11-3.cabba9e has 7 digits.
>
> Andy, clearly providing very key and crucial feedback

This vegetarian approves of this crucial change :)

~~ Ricardo

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

Andy Wingo <wingo@igalia.com> skribis:

> On Thu 21 Jan 2016 22:25, ludo@gnu.org (Ludovic Courtès) writes:
>
>> +2.0.11-3.deadbeef
>
> I thought you were vegetarian :)  2.0.11-3.cabba9e has 7 digits.

I like this more, indeed!  Thanks for the valuable feedback.  :-)

Ludo’.

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

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

Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> +
>> +It is a good idea to strip commit identifiers to, say, 7 digits so that
>> +they do not become aesthetically disturbing (assuming aesthetics have a
>> +role to play here.)  It is best to use the full commit identifiers in
>> +@code{origin}s, though, to avoid ambiguities.
>> +
>
> I would probably find this a little confusing if I didn’t already know
> what you meant.  Where should commit identifiers be stripped?  Are there
> more places than just the ‘version’ field?  Could we name the ‘version’
> field as an example?
>
> Is it only aesthetics or also a matter of keeping shebangs shorter (in
> case the output provides an interpreter that could end up in a shebang
> line).  The version is usually part of the output name, so maybe it
> would make sense to mention the ‘version’ field explicitly.

You’re right on both points.

How about this variant?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1685 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 0a67652..a8b9366 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -10130,6 +10130,38 @@ If we also wanted GTK+ 3.8.2, this would be packaged as
     ...))
 @end example
 
+@cindex version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases.  This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is.  Yet, it is sometimes necessary.  So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer.  Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot.  The resulting version string looks like this:
+
+@example
+2.0.11-3.cabba9e
+  ^    ^    ^
+  |    |    `-- upstream commit ID
+  |    |
+  |    `--- Guix package revision
+  |
+latest upstream version
+@end example
+
+It is a good idea to strip commit identifiers in the @code{version}
+field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
+aesthetics have a role to play here) as well as problems related to OS
+limits such as the maximum shebang length (127 bytes for the Linux
+kernel.)  It is best to use the full commit identifiers in
+@code{origin}s, though, to avoid ambiguities.
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions
 

[-- Attachment #3: Type: text/plain, Size: 23 bytes --]


Thanks!

Ludo’.

Re: Version numbers for VCS snapshots

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>>> +
>>> +It is a good idea to strip commit identifiers to, say, 7 digits so that
>>> +they do not become aesthetically disturbing (assuming aesthetics have a
>>> +role to play here.)  It is best to use the full commit identifiers in
>>> +@code{origin}s, though, to avoid ambiguities.
>>> +
>>
>> I would probably find this a little confusing if I didn’t already know
>> what you meant.  Where should commit identifiers be stripped?  Are there
>> more places than just the ‘version’ field?  Could we name the ‘version’
>> field as an example?
>>
>> Is it only aesthetics or also a matter of keeping shebangs shorter (in
>> case the output provides an interpreter that could end up in a shebang
>> line).  The version is usually part of the output name, so maybe it
>> would make sense to mention the ‘version’ field explicitly.
>
> You’re right on both points.
>
> How about this variant?

Beautiful.  Thanks!

~~ Ricardo

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
>>
>>> Ludovic Courtès <ludo@gnu.org> writes:
>>>
>>>> +
>>>> +It is a good idea to strip commit identifiers to, say, 7 digits so that
>>>> +they do not become aesthetically disturbing (assuming aesthetics have a
>>>> +role to play here.)  It is best to use the full commit identifiers in
>>>> +@code{origin}s, though, to avoid ambiguities.
>>>> +
>>>
>>> I would probably find this a little confusing if I didn’t already know
>>> what you meant.  Where should commit identifiers be stripped?  Are there
>>> more places than just the ‘version’ field?  Could we name the ‘version’
>>> field as an example?
>>>
>>> Is it only aesthetics or also a matter of keeping shebangs shorter (in
>>> case the output provides an interpreter that could end up in a shebang
>>> line).  The version is usually part of the output name, so maybe it
>>> would make sense to mention the ‘version’ field explicitly.
>>
>> You’re right on both points.
>>
>> How about this variant?
>
> Beautiful.  Thanks!

Pushed!

Ludo’.

Re: Version numbers for VCS snapshots

[Leo Famulari]

On Thu, Jan 21, 2016 at 10:05:36PM +0100, Ludovic Courtès wrote:
> Leo Famulari <leo@famulari.name> skribis:
> 
> > On Thu, Jan 21, 2016 at 10:40:41AM +0100, Ricardo Wurmus wrote:
> >> 
> >> Leo Famulari <leo@famulari.name> writes:
> >> 
> >> > That sounds good to me. There was some discussion of how much of the
> >> > hash to keep here:
> >> > http://lists.gnu.org/archive/html/guix-devel/2015-12/msg00136.html
> >> >
> >> > I like this method that I've seen in some of the packages, because it
> >> > keeps the version tidy while preserving the full hash:
> >> >
> >> > --8<---------------cut here---------------start------------->8---
> >> > (define-public hello
> >> >   (let ((commit "e8e46123cfe62170a2f7f79db6b471b66ae36947"))
> >> >     (package
> >> >       (name "hello")
> >> >       (version (string-append "2.10-1" (string-take commit 8)))
> >> >       (source (origin
> >> >                 (method git-fetch)
> >> >                 (uri (git-reference
> >> >                        (url "git://git.sv.gnu.org/hello.git")
> >> >                        (commit commit)))
> >> >                 (sha256
> >> >                 [...]
> >> > --8<---------------cut here---------------end--------------->8---
> >> 
> >> I like this approach (though I’ve been taking 9 characters of the commit
> >> ;)).
> >
> > I like 10 but I wanted to match your example upthread ;)
> 
> I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.

I stumbled across this email earlier, which reminded me of this
discussion about hash lengths:
https://lkml.org/lkml/2010/10/28/287

There are currently 13 7-character hash collisions in Guix's git repo:

$ git rev-list --objects --all | cut -c1-7 | sort | uniq -dc
      2 0d2b24c         
      2 11e0632
      2 1f3ab8d
      2 229bd6c
      2 7c4a7b7
      2 9ff8b63
      2 aa27b56
      2 c10c562
      2 d96cdce
      2 dab4329
      2 dc27d1c
      2 ea119a2
      2 f56cc27

Re: Version numbers for VCS snapshots

[Alex Kost]

Leo Famulari (2016-02-21 07:35 +0300) wrote:

> On Thu, Jan 21, 2016 at 10:05:36PM +0100, Ludovic Courtès wrote:
[...]
>> I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.
>
> I stumbled across this email earlier, which reminded me of this
> discussion about hash lengths:
> https://lkml.org/lkml/2010/10/28/287
>
> There are currently 13 7-character hash collisions in Guix's git repo:
>
> $ git rev-list --objects --all | cut -c1-7 | sort | uniq -dc
>       2 0d2b24c
>       2 11e0632
>       2 1f3ab8d
>       2 229bd6c
>       2 7c4a7b7
>       2 9ff8b63
>       2 aa27b56
>       2 c10c562
>       2 d96cdce
>       2 dab4329
>       2 dc27d1c
>       2 ea119a2
>       2 f56cc27

Hm, when I tried "git rev-list --objects --all" I got some ridiculous
number of lines (I pressed C-c C-c after about 78000 lines).  Does this
command really do what you wanted?  (I'm sorry I didn't RTFM well enough
to understand what it does).

I'm not sure if the following command is correct to find such
collisions, but it gives nothing (i.e., no collisions):

  git log --oneline | cut -c1-7 | sort | uniq -dc

-- 
Alex

Re: Version numbers for VCS snapshots

[Leo Famulari]

On Sun, Feb 21, 2016 at 12:17:19PM +0300, Alex Kost wrote:
> Leo Famulari (2016-02-21 07:35 +0300) wrote:
> 
> > On Thu, Jan 21, 2016 at 10:05:36PM +0100, Ludovic Courtès wrote:
> [...]
> >> I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.
> >
> > I stumbled across this email earlier, which reminded me of this
> > discussion about hash lengths:
> > https://lkml.org/lkml/2010/10/28/287
> >
> > There are currently 13 7-character hash collisions in Guix's git repo:
> >
> > $ git rev-list --objects --all | cut -c1-7 | sort | uniq -dc
> >       2 0d2b24c
> >       2 11e0632
> >       2 1f3ab8d
> >       2 229bd6c
> >       2 7c4a7b7
> >       2 9ff8b63
> >       2 aa27b56
> >       2 c10c562
> >       2 d96cdce
> >       2 dab4329
> >       2 dc27d1c
> >       2 ea119a2
> >       2 f56cc27
> 
> Hm, when I tried "git rev-list --objects --all" I got some ridiculous
> number of lines (I pressed C-c C-c after about 78000 lines).  Does this
> command really do what you wanted?  (I'm sorry I didn't RTFM well enough
> to understand what it does).

It lists the objects in the repository, so not just commits. I'm not
presenting this as evidence that something is wrong with our repo, just
that 7 characters is not enough to unambiguously refer to things in git
repos of projects our size. For example, with `git show`.

It's more of an informational link than a call to action. Although I am
updating all of our uses of git-reference to use the method we agreed
upon upthread, before any of those upstream repos grow too large for the
identifiers we are currently using.

> 
> I'm not sure if the following command is correct to find such
> collisions, but it gives nothing (i.e., no collisions):
> 
>   git log --oneline | cut -c1-7 | sort | uniq -dc

Indeed, we only have about 10000 commits. 6 characters is where we get
collisions in our log.

> 
> -- 
> Alex

Re: Version numbers for VCS snapshots

[Christopher Allan Webber]

Leo Famulari writes:

> On Sun, Feb 21, 2016 at 12:17:19PM +0300, Alex Kost wrote:
>> Leo Famulari (2016-02-21 07:35 +0300) wrote:
>> 
>> > On Thu, Jan 21, 2016 at 10:05:36PM +0100, Ludovic Courtès wrote:
>> [...]
>> >> I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.
>> >
>> > I stumbled across this email earlier, which reminded me of this
>> > discussion about hash lengths:
>> > https://lkml.org/lkml/2010/10/28/287
>> >
>> > There are currently 13 7-character hash collisions in Guix's git repo:
>> >
>> > $ git rev-list --objects --all | cut -c1-7 | sort | uniq -dc
>> >       2 0d2b24c
>> >       2 11e0632
>> >       2 1f3ab8d
>> >       2 229bd6c
>> >       2 7c4a7b7
>> >       2 9ff8b63
>> >       2 aa27b56
>> >       2 c10c562
>> >       2 d96cdce
>> >       2 dab4329
>> >       2 dc27d1c
>> >       2 ea119a2
>> >       2 f56cc27
>> 
>> Hm, when I tried "git rev-list --objects --all" I got some ridiculous
>> number of lines (I pressed C-c C-c after about 78000 lines).  Does this
>> command really do what you wanted?  (I'm sorry I didn't RTFM well enough
>> to understand what it does).
>
> It lists the objects in the repository, so not just commits. I'm not
> presenting this as evidence that something is wrong with our repo, just
> that 7 characters is not enough to unambiguously refer to things in git
> repos of projects our size. For example, with `git show`.
>
> It's more of an informational link than a call to action. Although I am
> updating all of our uses of git-reference to use the method we agreed
> upon upthread, before any of those upstream repos grow too large for the
> identifiers we are currently using.

Yes, short identifiers probably should not be relied upon.

For an entertaining article on the subject, I offer this one, which is
similar but in GPG land:
  http://www.asheesh.org/note/debian/short-key-ids-are-bad-news.html

Re: Version numbers for VCS snapshots

[Ludovic Courtès]

Christopher Allan Webber <cwebber@dustycloud.org> skribis:

> Leo Famulari writes:
>
>> On Sun, Feb 21, 2016 at 12:17:19PM +0300, Alex Kost wrote:
>>> Leo Famulari (2016-02-21 07:35 +0300) wrote:
>>> 
>>> > On Thu, Jan 21, 2016 at 10:05:36PM +0100, Ludovic Courtès wrote:
>>> [...]
>>> >> I prefer 7!  This is how Git usually truncates SHA1s, so it can’t be wrong.
>>> >
>>> > I stumbled across this email earlier, which reminded me of this
>>> > discussion about hash lengths:
>>> > https://lkml.org/lkml/2010/10/28/287
>>> >
>>> > There are currently 13 7-character hash collisions in Guix's git repo:
>>> >
>>> > $ git rev-list --objects --all | cut -c1-7 | sort | uniq -dc
>>> >       2 0d2b24c
>>> >       2 11e0632
>>> >       2 1f3ab8d
>>> >       2 229bd6c
>>> >       2 7c4a7b7
>>> >       2 9ff8b63
>>> >       2 aa27b56
>>> >       2 c10c562
>>> >       2 d96cdce
>>> >       2 dab4329
>>> >       2 dc27d1c
>>> >       2 ea119a2
>>> >       2 f56cc27
>>> 
>>> Hm, when I tried "git rev-list --objects --all" I got some ridiculous
>>> number of lines (I pressed C-c C-c after about 78000 lines).  Does this
>>> command really do what you wanted?  (I'm sorry I didn't RTFM well enough
>>> to understand what it does).
>>
>> It lists the objects in the repository, so not just commits. I'm not
>> presenting this as evidence that something is wrong with our repo, just
>> that 7 characters is not enough to unambiguously refer to things in git
>> repos of projects our size. For example, with `git show`.
>>
>> It's more of an informational link than a call to action. Although I am
>> updating all of our uses of git-reference to use the method we agreed
>> upon upthread, before any of those upstream repos grow too large for the
>> identifiers we are currently using.
>
> Yes, short identifiers probably should not be relied upon.

Agreed.  The manual suggests using full-length hashes to identify
commits (info "(guix) Version Numbers").  Commit 561360a (or should I
say 561360a589d2bea0b01b38aa9049b8e69cfad2e7? :-)) adds an example of
this.

It would be nice to have ‘guix lint’ check for show commit IDs in
‘git-reference’ objects.

Ludo’.