From 880d647d0f1a0ea0aea2af84fa2e99e3286b65a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Sun, 24 Jan 2016 21:42:32 +0100 Subject: [PATCH] doc: Add policy about version numbers for VCS snapshots. * doc/guix.texi (Version Numbers): Add paragraphs about VCS snapshot version numbers. --- doc/guix.texi | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index f4ba2af0b6..a650a55d51 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -10131,6 +10131,40 @@ If we also wanted GTK+ 3.8.2, this would be packaged as ...)) @end example +@c See , +@c for a discussion of what follows. +@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