feature: pname_version_normalization
start-date:
author: Anderson Torres
co-authors:
shepherd-team:
shepherd-leader:
related-issues:
Summary
Normalize the situation about the version
attribute used in Nixpkgs,
especially for snapshots .
Motivation
Nowadays, the most commonly used format for the pname
and version
attributes
is:
- For stable releases:
pname
reflects the software name;version
reflects the released version, without prepending alphabetical
prefixes such as "v", "version", "rel" etc.
- For unstable releases:
pname
reflects the software name;version
is a string following the formatunstable-YYYY-MM-DD
, where
YYYY-MM-DD
denotes the date when the code was fetched.
This is a simple and easy-to-understand format. However, it does not map very
well with the Nix function builtins.parseDrvName
:
It happens because builtins.parseDrvName.version
starts with a digit. This is
not a bug, but a deliberate design decision of Nix specification; therefore we
should strive to follow it, neither circumventing nor ignoring it.
That being said, version
attribute should start with a digit.
Furthermore, version
attribute should follow the semantics for upgrading as
stated in nix-env
manpage.
This document describes a format suitable to fix this problem while striving for
simplicity.
Detailed design
Terminology
Disclaimer: some of the terms below are borrowed from pkgsrc
guide plus a bit of git terminology, but
this document strives to be general and not overly attached to them.
- Program denotes the piece of software to be fetched and processed via Nixpkgs.
- Team denotes the maintainers of the program.
- This term makes no distinction among the various models of organization of a
team; it can denote from solitary programmers to business companies and
everything inbetween.
- This term makes no distinction among the various models of organization of a
- Source denotes the origin of the program.
- This term makes no distinction among precompiled, binary-only or
high-level code distributions.
- This term makes no distinction among precompiled, binary-only or
- Snapshot denotes the source of the program taken at a point of the time.
- Labeled snapshot denotes any snapshot explicitly labeled by its team.
- Unlabeled snapshot denotes any snapshot not explicitly labeled by its team.
- Release denotes any distributed snapshot, as defined by its team
- Branch denotes a logical sequence of snapshots, as identified by the program's
team;- Usually these branches are denoted by names such like
stable
,master
,
unstable
,trunk
,experimental
,staging
etc.;
- Usually these branches are denoted by names such like
Design
- For a labeled snapshot:
version
should be constituted of the version of the snapshot, as defined
by the upstream project, without any alphabetical characters (e.g. "v",
"rel") prepending it.
- For an unlabeled snapshot:
version
should be constituted of a concatenation of the elements below in
this order:- the version of the latest labeled snapshot, as defined above;
- If the project never released a labeled snapshot,
0_0
should be used
as default.
- If the project never released a labeled snapshot,
- the string
+unstable=YYYY-MM-DD
, whereYYYY-MM-DD
denotes the date
the mentioned unlabeled snapshot was distributed.
- Some atypical programs have special considerations:
- Linux kernel modules:
- Besides the rules established above for typical snapshots (whether labeled
or unlabeled),version
shoud have appended+linux=XX.XX.XX
, where
XX.XX.XX
is the corresponding Linux kernel version used to build the
aforementioned module.
- Besides the rules established above for typical snapshots (whether labeled
- Linux kernel modules:
Examples and Interactions
Some useful examples:
- Bochs is a typical Sourceforge-hosted project; its labeled snapshots can be
fetched from tarballs obtained via URLs like
https://sourceforge.net/projects/bochs/files/bochs/2.6.11/; for this
example, we havepname = "bochs"; version = "2.6.11";
. - MPV is a typical Github-hosted program; its labeled snapshots can be fetched
from tarballs obtained via URLs like
https://github.com/mpv-player/mpv/releases/tag/v0.33.1; for this example, we
get rid of the"v"
prepended to the version tag:pname = "mpv"; version = "0.33.1";
. -
SDL2 is hosted on Github; its latest labeled version can be downloaded from
https://github.com/libsdl-org/SDL/releases/tag/release-2.0.14; therefore we
havepname = "SDL2"; version = "2.0.14";
.However, this labeled version was released December 21, 2020, while the
latest change was done in May 28, 2021. Therefore, for this particular
unlabeled releases of SDL2, we havepname = "SDL2"; version = "2.0.14+unstable=2021-05-28";
. - Cardboard is a typical Gitlab-hosted program; it has no labeled release yet,
therefore we use0.0.0
as default stable version; the latest commit was made
on May 10, 2021; therefore, we havepname = "cardboard"; version = "0_0+unstable=2021-05-21";
. - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page,
https://github.com/Mange/rtl8192eu-linux-driver. It has no labeled release;
the latest code is from May 12, 2021. Supposing e.g. it was built for Linux
kernel version 5.10.01, we therefore havepname = "rtl8192eu"; version = "0_0+unstable=2021-05-12+linux=5.10.01";
.
Drawbacks
The main drawback is the conversion of the already existent expressions which
does not follow this proposal. It can be cumbersome and certainly require some
manual intervention, however it is amenable to automation.
Alternatives
The alternative is doing nothing. The impact of it is keeping the codebase
confusing and less discoverable.
Unresolved questions
- Allow some degree of freedom and extensibility for handling deviations, such
as programs whose teams employ different, non-standard naming schemes or
unusual releasing schedules.
Future work
- Update manuals and related documentation in order to reflect this standard.