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

1
2
3
4
5
6
7
8
9
# expected: { name = "mpv"; version = "0.35.15"; }
nix-repl> builtins.parseDrvName "mpv-0.35.15"
builtins.parseDrvName "mpv-0.35.15"
{ name = "mpv"; version = "0.35.15"; }

# expected: { name = "mpv"; version = "unstable-2021-05-03"; }
nix-repl> builtins.parseDrvName "mpv-unstable-2021-05-03"
builtins.parseDrvName "mpv-unstable-2021-05-03"
{ name = "mpv-unstable"; version = "2021-05-03"; }

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.
  • Source denotes the origin of the program.
    • This term makes no distinction among precompiled, binary-only or
      high-level code distributions.
  • 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.;

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.
    • the string +unstable=YYYY-MM-DD, where YYYY-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.

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 have pname = "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
    have pname = "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 have pname = "SDL2"; version = "2.0.14+unstable=2021-05-28";.

  • Cardboard is a typical Gitlab-hosted program; it has no labeled release yet,
    therefore we use 0.0.0 as default stable version; the latest commit was made
    on May 10, 2021; therefore, we have pname = "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 have pname = "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.
Edit
Pub: 30 May 2021 04:41 UTC
Edit: 17 Sep 2021 23:12 UTC
Views: 144