From b54350e99eebb23c0299197d05144866c58d3b5d Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 24 Sep 2021 18:59:06 -0300 Subject: [PATCH 01/19] Nixpkgs version normalization --- rfcs/0107-version-normalization.md | 182 +++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 rfcs/0107-version-normalization.md diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md new file mode 100644 index 000000000..a7965d57d --- /dev/null +++ b/rfcs/0107-version-normalization.md @@ -0,0 +1,182 @@ +--- +feature: nixpkgs_version_normalization +start-date: 2021-09-24 +author: Anderson Torres +co-authors: +shepherd-team: +shepherd-leader: +related-issues: +--- + +# Summary +[summary]: #summary + +Normalize the `version` attribute used in Nixpkgs' expresions. + +# Motivation +[motivation]: #motivation + +Nowadays, the most commonly used format for the `pname` and `version` attributes +along the Nixpkgs' expressions is: + +- For stable releases: + - `pname` reflects the software name; + - `version` reflects the released version. +- 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 generated. + +This is a simple and easy-to-understand format. + +However, it does not map very well with the Nix function +`builtins.parseDrvName`: + +```example +# 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 the `version` attribute returned by `builtins.parseDrvName` +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 issue while striving for +simplicity. + +# Detailed design +[design]: #detailed-design + +## Terminology + +_Disclaimer_: whereas some of the terms enumerated below are borrowed from +[pkgsrc guide](https://www.netbsd.org/docs/pkgsrc/) plus a bit of terminology +employed by git, this document aims to be general, not being overly attached to +them. + +- Program denotes the piece of software to be fetched and processed via Nixpkgs. + - This term makes no distinction about the immediate or intended uses of the + program; it can range from non-interactive programs to full GUI + applications, even including filesets intended as input to other programs + (such as firmwares and fonts). +- Team denotes the maintainers of the program. + - This term makes no distinction among the various models of organization of a + team; it ranges from a solitary programmer to a business company - 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. + - Alphabetical characters after the first should be maintained, except + optionally those clearly used as separators, in which case they are + replaced by dots (emulating a typical semver). + +- 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 +[examples-and-interactions]: #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 + ; 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 + ; 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 + ; 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, + . 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 +[drawbacks]: #drawbacks + +The main drawback is the conversion of the already existent expressions which +does not follow the format proposed here. It can require a degree of manual +intervention. However, this task is easily sprintable and amenable to +automation. + +# Alternatives +[alternatives]: #alternatives + +The alternative is doing nothing. The impact of it is keeping the Nixpkgs +codebase confusing, less discoverable and incompatible with +`builtins.parseDrvName`. + +# Unresolved questions +[unresolved]: #unresolved-questions + +- Allow some degree of freedom and extensibility for handling deviations, such + different, non-standard naming schemes or unusual releasing schedules + eventually employed by many teams. + +- Interactions between `pname` and `version`, like multi-branch releases. + +# Future work +[future]: #future-work + +- Update expressions that do not follow this proposal. +- Update manuals and related documentation in order to reflect this proposal for + future expressions. From 0ae28d1e15a88abcc129be165a22a59ed14ead4d Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 24 Sep 2021 21:05:55 -0300 Subject: [PATCH 02/19] Fix cardboard example --- rfcs/0107-version-normalization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index a7965d57d..b4d64c5f4 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -140,7 +140,7 @@ Some useful examples: "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 + therefore we use `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";`. From 250e5be9d0e7a29fb6fa3bfddbec6938e40d8ebd Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 24 Sep 2021 21:20:10 -0300 Subject: [PATCH 03/19] Fix the definition of version --- rfcs/0107-version-normalization.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index b4d64c5f4..66c5d26d2 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -92,11 +92,12 @@ them. - 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. - - Alphabetical characters after the first should be maintained, except - optionally those clearly used as separators, in which case they are - replaced by dots (emulating a typical semver). + by the program team, without any alphabetical characters (e.g. "v", "rel") + prepending it. + - Alphabetical characters following the first numerical character of version + (as defined above) should be maintained, except optionally those clearly + used as separators, in which case they are replaced by dots (emulating a + typical dot-separated version). - For an unlabeled snapshot: - `version` should be constituted of a concatenation of the elements below in From 3a326d8772873ccf0ab52a53aa536520b1ef05bc Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 24 Sep 2021 23:09:29 -0300 Subject: [PATCH 04/19] Clarify the rule of branches in multiple-branch sources --- rfcs/0107-version-normalization.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 66c5d26d2..da18d4451 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -102,7 +102,8 @@ them. - 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; + - the version of the latest labeled snapshot (on the same branch, when + applicable), 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 From f7827278ceea1889ace805c82a6049ed103bb443 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 24 Sep 2021 23:59:26 -0300 Subject: [PATCH 05/19] Add Python as an example of multiple-branches program release --- rfcs/0107-version-normalization.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index da18d4451..7aaab768e 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -146,6 +146,21 @@ Some useful examples: on May 10, 2021; therefore, we have `pname = "cardboard"; version = "0_0+unstable=2021-05-21";`. +- Python is a famous programming language and interpreter. Before the + deprecation of its 2.x series in 2020, Python had two release branches, + popularly known as 'Python 2' and 'Python 3'. Indeed it reflected in many + package managers, especially Nixpkgs, that employed `python2` and `python3` as + `pname`s. + + As an exercise of imagination, suppose the following scenario: + + Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch + released at 2008-12-04 would have `version="2.6+unstable=2008-12-04"`. + + At the same time, Python 3.0 was released 2008-12-03; an unlabeled snapshot of + Python 3 branch released at 2008-12-04 would have + `version="3.0+unstable=2008-12-04"`. + - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page, . It has no labeled release; the latest code is from May 12, 2021. Supposing e.g. it was built for Linux From 5d672e2441f310f63da27956a275ddb7dd4d0ad4 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Sat, 25 Sep 2021 00:46:29 -0300 Subject: [PATCH 06/19] Add an extra example of branch denotation --- rfcs/0107-version-normalization.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 7aaab768e..c9285771e 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -85,8 +85,9 @@ them. - 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 as `stable`, `master`, + `unstable`, `trunk`, `experimental`, `staging`, `X.Y` (where `X` and + `Y` are numbers) etc. ## Design From 533f38ec134e045ed599933835fbc8f86e74c921 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Tue, 28 Sep 2021 02:25:12 -0300 Subject: [PATCH 07/19] Use 0.pre as default dummy release Also, minor reword and formatting. --- rfcs/0107-version-normalization.md | 50 +++++++++++++++++------------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index c9285771e..24aee41bd 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -105,8 +105,8 @@ them. this order: - the version of the latest labeled snapshot (on the same branch, when applicable), 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, `0.pre` should be + used as default. - the string `+unstable=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date the mentioned unlabeled snapshot was distributed. @@ -124,36 +124,41 @@ Some useful examples: - Bochs is a typical Sourceforge-hosted project; its labeled snapshots can be fetched from tarballs obtained via URLs like - ; for this - example, we have `pname = "bochs"; version = "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 - ; for this example, we - get rid of the `"v"` prepended to the version tag: `pname = "mpv"; version = - "0.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 - ; therefore we + . 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";`. + 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.pre` as default dummy stable version; further, the latest + commit was made on May 10, 2021. -- Cardboard is a typical Gitlab-hosted program; it has no labeled release yet, - therefore we use `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";`. + Therefore, we have `pname = "cardboard"; version = + "0.pre+unstable=2021-05-21";`. - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, - popularly known as 'Python 2' and 'Python 3'. Indeed it reflected in many - package managers, especially Nixpkgs, that employed `python2` and `python3` as - `pname`s. + popularly known as 'Python 2' and 'Python 3'. Indeed this peculiar situation + reflected in many package managers, especially Nixpkgs, that employed + `python2` and `python3` as `pname`s for these particular programs. - As an exercise of imagination, suppose the following scenario: + As an exercise of imagination, suppose the scenarios described below: Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch released at 2008-12-04 would have `version="2.6+unstable=2008-12-04"`. @@ -166,15 +171,16 @@ Some useful examples: . 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";`. + "0.pre+unstable=2021-05-12+linux=5.10.01";`. # Drawbacks [drawbacks]: #drawbacks The main drawback is the conversion of the already existent expressions which does not follow the format proposed here. It can require a degree of manual -intervention. However, this task is easily sprintable and amenable to -automation. +intervention and code review, especially for machine-generated expressions (such +as Lua or Node library sets). However, this task is easily sprintable and +amenable to automation. # Alternatives [alternatives]: #alternatives From f656429861df436b7d91235c82bf014255309280 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 1 Oct 2021 00:29:00 -0300 Subject: [PATCH 08/19] Reword it in order to include the issue about upgradability --- rfcs/0107-version-normalization.md | 32 ++++++++++++++++-------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 24aee41bd..fec86f6b3 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -27,9 +27,10 @@ along the Nixpkgs' expressions is: - `version` is a string following the format `unstable-YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date when the code was generated. -This is a simple and easy-to-understand format. +This is a simple and easy-to-understand format. Nonetheless, there are some +problems with it. -However, it does not map very well with the Nix function +First, it does not map very well with the Nix function `builtins.parseDrvName`: ```example @@ -44,18 +45,18 @@ builtins.parseDrvName "mpv-unstable-2021-05-03" { name = "mpv-unstable"; version = "2021-05-03"; } ``` -It happens because the `version` attribute returned by `builtins.parseDrvName` -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. +It happens because the `version` attribute in the set returned by +`builtins.parseDrvName` always starts with a digit. This is a deliberate design +decision of Nix specification, and as such it should not be regarded as a "bug"; +therefore, we should strive to follow it, neither circumventing nor ignoring it. -That being said, `version` attribute should start with a digit. +Further, the `version` attribute should be crafted to satisfy the expected +upgrading semantics stated in `nix-env` manpage and implemented by +`builtins.compareVersions` -- even when the raw version of the original program +does not meet this expectation. -Furthermore, `version` attribute should follow the semantics for upgrading as -stated in `nix-env` manpage. - -This document describes a format suitable to fix this issue while striving for -simplicity. +This document describes a format suitable to fix these issues, while keeping it +understandable and striving for simplicity. # Detailed design [design]: #detailed-design @@ -103,8 +104,9 @@ them. - 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 (on the same branch, when - applicable), as defined above; + - the version of the latest previous labeled snapshot (on the same branch, + when applicable), according to the rules defined before for labeled + snapshots; - If the project never released a labeled snapshot, `0.pre` should be used as default. - the string `+unstable=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date @@ -155,7 +157,7 @@ Some useful examples: - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, popularly known as 'Python 2' and 'Python 3'. Indeed this peculiar situation - reflected in many package managers, especially Nixpkgs, that employed + reflected in many package management teams, especially Nixpkgs, that employed `python2` and `python3` as `pname`s for these particular programs. As an exercise of imagination, suppose the scenarios described below: From 0083a07ec8a3817803239706016aaa6f20616f15 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Mon, 11 Oct 2021 00:04:45 -0300 Subject: [PATCH 09/19] Cite compareVersions --- rfcs/0107-version-normalization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index fec86f6b3..1fb20caf1 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -189,7 +189,7 @@ amenable to automation. The alternative is doing nothing. The impact of it is keeping the Nixpkgs codebase confusing, less discoverable and incompatible with -`builtins.parseDrvName`. +`builtins.parseDrvName` and `builtins.compareVersions`. # Unresolved questions [unresolved]: #unresolved-questions From 9733bbc5945840037c20d63460dac78afc0e6bdf Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Mon, 11 Oct 2021 00:05:37 -0300 Subject: [PATCH 10/19] Cite flakes --- rfcs/0107-version-normalization.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 1fb20caf1..e894752ab 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -200,6 +200,9 @@ codebase confusing, less discoverable and incompatible with - Interactions between `pname` and `version`, like multi-branch releases. +- Legacy issues and integration with future implementations of Nix and Nixpkgs, + epecially the Flakes framework. + # Future work [future]: #future-work From 6b7cb1fcce618be93e2e1ad57ff9f56304bb3cca Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Mon, 11 Oct 2021 00:15:19 -0300 Subject: [PATCH 11/19] Change `unstable` to `date` --- rfcs/0107-version-normalization.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index e894752ab..da6c6b218 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -109,7 +109,7 @@ them. snapshots; - If the project never released a labeled snapshot, `0.pre` should be used as default. - - the string `+unstable=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date + - the string `+date=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date the mentioned unlabeled snapshot was distributed. - Some atypical programs have special considerations: @@ -145,14 +145,14 @@ Some useful examples: 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";`. + "SDL2"; version = "2.0.14+date=2021-05-28";`. - Cardboard is a typical Gitlab-hosted program. It has no labeled release yet, therefore we use `0.pre` as default dummy stable version; further, the latest commit was made on May 10, 2021. Therefore, we have `pname = "cardboard"; version = - "0.pre+unstable=2021-05-21";`. + "0.pre+date=2021-05-21";`. - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, @@ -163,17 +163,17 @@ Some useful examples: As an exercise of imagination, suppose the scenarios described below: Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch - released at 2008-12-04 would have `version="2.6+unstable=2008-12-04"`. + released at 2008-12-04 would have `version="2.6+date=2008-12-04"`. At the same time, Python 3.0 was released 2008-12-03; an unlabeled snapshot of Python 3 branch released at 2008-12-04 would have - `version="3.0+unstable=2008-12-04"`. + `version="3.0+date=2008-12-04"`. - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page, . 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.pre+unstable=2021-05-12+linux=5.10.01";`. + "0.pre+date=2021-05-12+linux=5.10.01";`. # Drawbacks [drawbacks]: #drawbacks From 1ed9b2e362e32ac4685d37dedb55ec321cc826be Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 12 Nov 2021 14:12:13 -0300 Subject: [PATCH 12/19] Clarifications after some feedback --- rfcs/0107-version-normalization.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index da6c6b218..109c7d618 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -25,7 +25,7 @@ along the Nixpkgs' expressions is: - 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 generated. + `YYYY-MM-DD` denotes the date when the code was released. This is a simple and easy-to-understand format. Nonetheless, there are some problems with it. @@ -51,7 +51,7 @@ decision of Nix specification, and as such it should not be regarded as a "bug"; therefore, we should strive to follow it, neither circumventing nor ignoring it. Further, the `version` attribute should be crafted to satisfy the expected -upgrading semantics stated in `nix-env` manpage and implemented by +upgrading semantics stated in the manual pages, as effectively implemented by `builtins.compareVersions` -- even when the raw version of the original program does not meet this expectation. @@ -151,7 +151,7 @@ Some useful examples: therefore we use `0.pre` as default dummy stable version; further, the latest commit was made on May 10, 2021. - Therefore, we have `pname = "cardboard"; version = + Therefore, for this particular commit have `pname = "cardboard"; version = "0.pre+date=2021-05-21";`. - Python is a famous programming language and interpreter. Before the @@ -179,16 +179,18 @@ Some useful examples: [drawbacks]: #drawbacks The main drawback is the conversion of the already existent expressions which -does not follow the format proposed here. It can require a degree of manual +does not follow the format proposed here. It can possibly require manual intervention and code review, especially for machine-generated expressions (such -as Lua or Node library sets). However, this task is easily sprintable and -amenable to automation. +as Lua, Emacs Lisp or Node library sets). + +Nonetheless, this task can be done incrementally, is easily sprintable, and +easily amenable to automation. # Alternatives [alternatives]: #alternatives The alternative is doing nothing. The impact of it is keeping the Nixpkgs -codebase confusing, less discoverable and incompatible with +codebase confusing, inconsistent, less discoverable and incompatible with `builtins.parseDrvName` and `builtins.compareVersions`. # Unresolved questions @@ -198,14 +200,18 @@ codebase confusing, less discoverable and incompatible with different, non-standard naming schemes or unusual releasing schedules eventually employed by many teams. -- Interactions between `pname` and `version`, like multi-branch releases. +- Interactions between `pname` and `version`, like multi-branch releases and + configuration options. - Legacy issues and integration with future implementations of Nix and Nixpkgs, epecially the Flakes framework. + +- Discussions about making `version` a data structure or abstract datatype. # Future work [future]: #future-work - Update expressions that do not follow this proposal. + - Update manuals and related documentation in order to reflect this proposal for future expressions. From 083116c0be0315977d7852b02b3f54c1fb766e62 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 12 Nov 2021 14:15:10 -0300 Subject: [PATCH 13/19] Cite Repology --- rfcs/0107-version-normalization.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 109c7d618..0efcd8059 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -200,13 +200,16 @@ codebase confusing, inconsistent, less discoverable and incompatible with different, non-standard naming schemes or unusual releasing schedules eventually employed by many teams. + - Regarding this, discuss about making `version` a data structure or abstract + datatype. + - Interactions between `pname` and `version`, like multi-branch releases and configuration options. - Legacy issues and integration with future implementations of Nix and Nixpkgs, epecially the Flakes framework. - -- Discussions about making `version` a data structure or abstract datatype. + +- Integration and interfacing with package databases like Repology. # Future work [future]: #future-work From 3057ea97a1a416a213d663f2bd897733de446bb7 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 4 Mar 2022 10:45:31 -0300 Subject: [PATCH 14/19] Cite repology as an example of external package monitoring service --- rfcs/0107-version-normalization.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 0efcd8059..f465eed6b 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -55,6 +55,9 @@ upgrading semantics stated in the manual pages, as effectively implemented by `builtins.compareVersions` -- even when the raw version of the original program does not meet this expectation. +Besides, Nixpkgs should provide a consistent interface to external package +monitoring services like [Repology](https://repology.org/). + This document describes a format suitable to fix these issues, while keeping it understandable and striving for simplicity. From 79c5ea17933027a4044d72fde2de2a2d019a6eee Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 4 Mar 2022 10:50:37 -0300 Subject: [PATCH 15/19] Rewording --- rfcs/0107-version-normalization.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index f465eed6b..96e9535d6 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -46,9 +46,9 @@ builtins.parseDrvName "mpv-unstable-2021-05-03" ``` It happens because the `version` attribute in the set returned by -`builtins.parseDrvName` always starts with a digit. This is a deliberate design -decision of Nix specification, and as such it should not be regarded as a "bug"; -therefore, we should strive to follow it, neither circumventing nor ignoring it. +`builtins.parseDrvName` always starts with a digit. It happens by a deliberate +design decision, and as such it should not be regarded as a "bug"; therefore, we +should strive to follow it, neither circumventing nor ignoring it. Further, the `version` attribute should be crafted to satisfy the expected upgrading semantics stated in the manual pages, as effectively implemented by @@ -182,19 +182,19 @@ Some useful examples: [drawbacks]: #drawbacks The main drawback is the conversion of the already existent expressions which -does not follow the format proposed here. It can possibly require manual -intervention and code review, especially for machine-generated expressions (such -as Lua, Emacs Lisp or Node library sets). +does not follow the format proposed here, possibly requiring manual intervention +and code review, especially for machine-generated expressions (such as Lua, +Emacs Lisp or Node library sets). -Nonetheless, this task can be done incrementally, is easily sprintable, and -easily amenable to automation. +Nonetheless, this task is easily sprintable, can be done incrementally, and is +amenable to automation. # Alternatives [alternatives]: #alternatives The alternative is doing nothing. The impact of it is keeping the Nixpkgs -codebase confusing, inconsistent, less discoverable and incompatible with -`builtins.parseDrvName` and `builtins.compareVersions`. +codebase incompatible with `builtins.parseDrvName` and +`builtins.compareVersions`, confusing, inconsistent and discoverable. # Unresolved questions [unresolved]: #unresolved-questions From 0a6e2fcfaf01d64005ff8ce0469b62f4639add3f Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Fri, 4 Mar 2022 10:46:36 -0300 Subject: [PATCH 16/19] Change `+` by `,` as separator Being a metacharacter, `+` can be a source of nasty bugs; it indeed was in the recent past: https://github.com/NixOS/nixpkgs/commit/17b1055d652f6ffe6b41516c2b667e09ab024b66 --- rfcs/0107-version-normalization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 96e9535d6..8221108e1 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -112,13 +112,13 @@ them. snapshots; - If the project never released a labeled snapshot, `0.pre` should be used as default. - - the string `+date=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date + - the string `,date=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 + 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. @@ -148,14 +148,14 @@ Some useful examples: latest change was done in May 28, 2021. Therefore, for this particular unlabeled releases of SDL2, we have `pname = - "SDL2"; version = "2.0.14+date=2021-05-28";`. + "SDL2"; version = "2.0.14,date=2021-05-28";`. - Cardboard is a typical Gitlab-hosted program. It has no labeled release yet, therefore we use `0.pre` as default dummy stable version; further, the latest commit was made on May 10, 2021. Therefore, for this particular commit have `pname = "cardboard"; version = - "0.pre+date=2021-05-21";`. + "0.pre,date=2021-05-21";`. - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, @@ -166,17 +166,17 @@ Some useful examples: As an exercise of imagination, suppose the scenarios described below: Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch - released at 2008-12-04 would have `version="2.6+date=2008-12-04"`. + released at 2008-12-04 would have `version="2.6,date=2008-12-04"`. At the same time, Python 3.0 was released 2008-12-03; an unlabeled snapshot of Python 3 branch released at 2008-12-04 would have - `version="3.0+date=2008-12-04"`. + `version="3.0,date=2008-12-04"`. - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page, . 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.pre+date=2021-05-12+linux=5.10.01";`. + "0.pre,date=2021-05-12,linux=5.10.01";`. # Drawbacks [drawbacks]: #drawbacks From 8ca41bfeabfb0cef9a89378439ed4717653948e2 Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Tue, 15 Mar 2022 22:52:55 -0300 Subject: [PATCH 17/19] Revert "Change `+` by `,` as separator" This reverts commit 0a6e2fcfaf01d64005ff8ce0469b62f4639add3f. Unfortunately, `,` is an illegal character. The search for the holy graal continues. --- rfcs/0107-version-normalization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 8221108e1..96e9535d6 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -112,13 +112,13 @@ them. snapshots; - If the project never released a labeled snapshot, `0.pre` should be used as default. - - the string `,date=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date + - the string `+date=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 + 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. @@ -148,14 +148,14 @@ Some useful examples: latest change was done in May 28, 2021. Therefore, for this particular unlabeled releases of SDL2, we have `pname = - "SDL2"; version = "2.0.14,date=2021-05-28";`. + "SDL2"; version = "2.0.14+date=2021-05-28";`. - Cardboard is a typical Gitlab-hosted program. It has no labeled release yet, therefore we use `0.pre` as default dummy stable version; further, the latest commit was made on May 10, 2021. Therefore, for this particular commit have `pname = "cardboard"; version = - "0.pre,date=2021-05-21";`. + "0.pre+date=2021-05-21";`. - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, @@ -166,17 +166,17 @@ Some useful examples: As an exercise of imagination, suppose the scenarios described below: Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch - released at 2008-12-04 would have `version="2.6,date=2008-12-04"`. + released at 2008-12-04 would have `version="2.6+date=2008-12-04"`. At the same time, Python 3.0 was released 2008-12-03; an unlabeled snapshot of Python 3 branch released at 2008-12-04 would have - `version="3.0,date=2008-12-04"`. + `version="3.0+date=2008-12-04"`. - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page, . 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.pre,date=2021-05-12,linux=5.10.01";`. + "0.pre+date=2021-05-12+linux=5.10.01";`. # Drawbacks [drawbacks]: #drawbacks From 5b35dd4fc85b99beaac1f636aa576dc7bb3ffdfa Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Sat, 17 Sep 2022 18:23:33 -0300 Subject: [PATCH 18/19] Change the separator from + to : Addresses the dreadful bug fixed on https://github.com/NixOS/nixpkgs/pull/146323 --- rfcs/0107-version-normalization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index 96e9535d6..d403d8dc7 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -112,13 +112,13 @@ them. snapshots; - If the project never released a labeled snapshot, `0.pre` should be used as default. - - the string `+date=YYYY-MM-DD`, where `YYYY-MM-DD` denotes the date + - the string `:date=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 + 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. @@ -148,14 +148,14 @@ Some useful examples: latest change was done in May 28, 2021. Therefore, for this particular unlabeled releases of SDL2, we have `pname = - "SDL2"; version = "2.0.14+date=2021-05-28";`. + "SDL2"; version = "2.0.14:date=2021-05-28";`. - Cardboard is a typical Gitlab-hosted program. It has no labeled release yet, therefore we use `0.pre` as default dummy stable version; further, the latest commit was made on May 10, 2021. Therefore, for this particular commit have `pname = "cardboard"; version = - "0.pre+date=2021-05-21";`. + "0.pre:date=2021-05-21";`. - Python is a famous programming language and interpreter. Before the deprecation of its 2.x series in 2020, Python had two release branches, @@ -166,17 +166,17 @@ Some useful examples: As an exercise of imagination, suppose the scenarios described below: Python 2.6 was released 2008-10-01; an unlabeled snapshot of Python 2 branch - released at 2008-12-04 would have `version="2.6+date=2008-12-04"`. + released at 2008-12-04 would have `version="2.6:date=2008-12-04"`. At the same time, Python 3.0 was released 2008-12-03; an unlabeled snapshot of Python 3 branch released at 2008-12-04 would have - `version="3.0+date=2008-12-04"`. + `version="3.0:date=2008-12-04"`. - The Linux drivers for Realtek rtl8192eu can be fetched from a Github page, . 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.pre+date=2021-05-12+linux=5.10.01";`. + "0.pre:date=2021-05-12:linux=5.10.01";`. # Drawbacks [drawbacks]: #drawbacks From fba4031f6d5a8c27deffe8153d8fd66962dda197 Mon Sep 17 00:00:00 2001 From: Linus Heckemann Date: Wed, 2 Nov 2022 16:52:02 +0100 Subject: [PATCH 19/19] 107: add shepherd metadata --- rfcs/0107-version-normalization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0107-version-normalization.md b/rfcs/0107-version-normalization.md index d403d8dc7..acdf6a9b5 100644 --- a/rfcs/0107-version-normalization.md +++ b/rfcs/0107-version-normalization.md @@ -3,8 +3,8 @@ feature: nixpkgs_version_normalization start-date: 2021-09-24 author: Anderson Torres co-authors: -shepherd-team: -shepherd-leader: +shepherd-team: @7c6f434c @SuperSandro2000 @jeff-hykin +shepherd-leader: @7c6f434c related-issues: ---