summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2016-01-24 21:42:32 +0100
committerLudovic Courtès <ludo@gnu.org>2016-01-25 00:11:22 +0100
commit880d647d0f1a0ea0aea2af84fa2e99e3286b65a1 (patch)
treed2d80b0a245d8ce69aca7781b4114036f856f7b5 /doc
parent24a8ef3ba195ef7f19c574722995ae2ed6886689 (diff)
downloadguix-880d647d0f1a0ea0aea2af84fa2e99e3286b65a1.tar.gz
doc: Add policy about version numbers for VCS snapshots.
* doc/guix.texi (Version Numbers): Add paragraphs about VCS snapshot
version numbers.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi34
1 files changed, 34 insertions, 0 deletions
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 <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
+@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