Re: Version numbers for VCS snapshots

[Ludovic Courtès]

Ricardo Wurmus <address@hidden> skribis:

> Ben Woodcroft <address@hidden> 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’.

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
 
address@hidden 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:
+
address@hidden
+2.0.11-3.deadbeef
+  ^    ^    ^
+  |    |    `-- upstream commit ID
+  |    |
+  |    `--- Guix package revision
+  |
+latest upstream version
address@hidden 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
address@hidden, though, to avoid ambiguities.
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions