6.7.3 Version Numbers

We usually package only the latest version of a given free software
project. But sometimes, for instance for incompatible library versions,
two (or more) versions of the same package are needed. These require
different Scheme variable names. We use the name as defined
in Package Naming
for the most recent version; previous versions use the same name, suffixed
by - and the smallest prefix of the version number that may
distinguish the two versions.

The name inside the package definition is the same for all versions of a
package and does not contain any version number.

For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:

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 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 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:

It is a good idea to strip commit identifiers in the 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
origins, though, to avoid ambiguities. A typical package
definition may look like this: