From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Version numbers for VCS snapshots Date: Thu, 21 Jan 2016 22:25:11 +0100 Message-ID: <877fj2wrpk.fsf@gnu.org> References: <874mem8mwx.fsf@gnu.org> <8737u344ov.fsf@elephly.net> <87twmjp2qs.fsf_-_@gnu.org> <56A063D1.80608@uq.edu.au> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:57746) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMMjH-0003vZ-1C for guix-devel@gnu.org; Thu, 21 Jan 2016 16:25:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMMjD-0003SP-0S for guix-devel@gnu.org; Thu, 21 Jan 2016 16:25:18 -0500 In-Reply-To: (Ricardo Wurmus's message of "Thu, 21 Jan 2016 10:44:44 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Ricardo Wurmus Cc: guix-devel@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Ricardo Wurmus skribis: > Ben Woodcroft writes: > >> On 12/01/16 19:26, Ludovic Court=C3=A8s wrote: [...] >>> So, a Git snapshot=E2=80=99s version number could be: >>> >>> 2.0.11-3.deadbeef >>> ^ ^ ^ >>> | | `=E2=80=94 upstream commit ID >>> | | >>> | `=E2=80=94=E2=80=94 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=E2=80=99t always= use > =E2=80=9C-=E2=80=9D to separate the upstream version from the revision + = commit ID (or > did only I do this wrong?). Some packages use =E2=80=9C.=E2=80=9D, which= is what > prompted me to ask for clarification. If there are no objections, I=E2=80=99ll commit the attached patch, which w= ill make it Official Policy. Thoughts? Ludo=E2=80=99. --=-=-= Content-Type: text/x-patch Content-Disposition: inline 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 --=-=-=--