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: Sat, 23 Jan 2016 23:00:19 +0100 Message-ID: <87a8nwq7m4.fsf@gnu.org> References: <874mem8mwx.fsf@gnu.org> <8737u344ov.fsf@elephly.net> <87twmjp2qs.fsf_-_@gnu.org> <56A063D1.80608@uq.edu.au> <877fj2wrpk.fsf@gnu.org> <87d1suvbev.fsf@mdc-berlin.de> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:54130) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aN6EM-0001kw-KZ for guix-devel@gnu.org; Sat, 23 Jan 2016 17:00:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aN6EJ-0005uP-Dj for guix-devel@gnu.org; Sat, 23 Jan 2016 17:00:26 -0500 In-Reply-To: <87d1suvbev.fsf@mdc-berlin.de> (Ricardo Wurmus's message of "Thu, 21 Jan 2016 23:02:32 +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: > Ludovic Court=C3=A8s writes: > >> + >> +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. >> + > > I would probably find this a little confusing if I didn=E2=80=99t already= know > what you meant. Where should commit identifiers be stripped? Are there > more places than just the =E2=80=98version=E2=80=99 field? Could we name= the =E2=80=98version=E2=80=99 > field as an example? > > Is it only aesthetics or also a matter of keeping shebangs shorter (in > case the output provides an interpreter that could end up in a shebang > line). The version is usually part of the output name, so maybe it > would make sense to mention the =E2=80=98version=E2=80=99 field explicitl= y. You=E2=80=99re right on both points. How about this variant? --=-=-= Content-Type: text/x-patch Content-Disposition: inline diff --git a/doc/guix.texi b/doc/guix.texi index 0a67652..a8b9366 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -10130,6 +10130,38 @@ 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.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 --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Thanks! Ludo=E2=80=99. --=-=-=--