Ricardo Wurmus <ricardo.wur...@mdc-berlin.de> skribis:
> Ben Woodcroft <b.woodcr...@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’.
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
