SemVer versioning

piegames commented

2025-04-13 12:37:36 +00:00

Member

Currently, the version tags are

2.92.0
2.92.0-1
2.92.0-2
etc.

This is a valid scheme on its own, however it also is valid SemVer syntax, and using SemVer semantics we get 2.92.0-1 < 2.92.0-2 < 2.92.0. This is because - is a prerelease marker. Npins tries to interpret tags using SemVer, so it breaks on this (workaround: --pre-releases --version-upper-bound 2.92.0). I see several potential solutions:

Use -0 suffix to tag initial releases: 2.92.0. This makes all releases pre-releases, and thus gives the correct SemVer ordering. Downsides:

Users must pass --pre-releases to npins, and until they do npins will find the last release prior to this practice, which will soon be outdated. (Retracting tags might be an option, but different can of worms)

Use three-dot release numbers: 2.92.0.1. This would not be SemVer compatible anymore, but it could be made to parse just fine in practice (npins currently parses it, but I just checked and the library does the wrong semantics atm).
Decouple the versioning of this repository and Lix. The Lix version could still be added as build metadata: 3+2.92.0. The issue here is that it works well as long as all Lix releases are monotonically increasing. As soon as a patch bump to an older version gets released, this kinda requires special handling.
Do nothing.

Currently, the version tags are 2.92.0 2.92.0-1 2.92.0-2 etc. This is a valid scheme on its own, however it also is valid SemVer syntax, and using SemVer semantics we get 2.92.0-1 < 2.92.0-2 < 2.92.0. This is because `-` is a prerelease marker. Npins tries to interpret tags using SemVer, so it breaks on this (workaround: `--pre-releases --version-upper-bound 2.92.0`). I see several potential solutions: 1. Use -0 suffix to tag initial releases: `2.92.0`. This makes all releases pre-releases, and thus gives the correct SemVer ordering. Downsides: - Users must pass `--pre-releases` to npins, and until they do npins will find the last release prior to this practice, which will soon be outdated. (Retracting tags might be an option, but different can of worms) 2. Use three-dot release numbers: `2.92.0.1`. This would not be SemVer compatible anymore, but it could be made to parse just fine in practice (npins currently parses it, but I just checked and the library does the wrong semantics atm). 3. Decouple the versioning of this repository and Lix. The Lix version could still be added as build metadata: `3+2.92.0`. The issue here is that it works well as long as all Lix releases are monotonically increasing. As soon as a patch bump to an older version gets released, this kinda requires special handling. 4. Do nothing.

raito was assigned by piegames

2025-04-13 12:37:36 +00:00

pennae commented

2025-04-13 13:52:58 +00:00

Owner

option 3 and 1 combined sounds like the best one. perhaps one major version per lix "major" (ie 1=2.90, 2=2.91, 3=2.92), copy the lix "minor" into the module minor, patches for nixpkgs-related changes, build metadata to very explicitly specify which lix it's for without having to know the version scheme. maybe even add the date to the build metadata?

jade commented

2025-04-13 17:55:26 +00:00

Owner

I am not sure if we should change our approach from traditional distro versioning to semver just because someone decided to misinterpret our version number as semver. Especially because the proposed versions here are super confusing.

One unintended consequence of this is that I'm guessing that the way that npins is using this in practice means that it's implicitly grabbing the latest version of lix and the module and hoping that by misinterpreting them as semver, they're matching. Unlike flakes where the module's expected lix version is encoded in the module itself via its lock file, I'm guessing that npins manages both the module and lix separately.

That separate management really isn't the intent of using the module on stable versions, and is kinda fragile. The intended method is that the module should provide the lix version, and we should fix our entry points for non flakes so it does that.

Also I think this question will be made somewhat obsolete by adding stable branches without having to mangle the version numbers in the tags.

Obviously for HEAD the lix and lix-module are just main for both and you update both every time.

I am not sure if we should change our approach from traditional distro versioning to semver just because someone decided to misinterpret our version number as semver. Especially because the proposed versions here are super confusing. One unintended consequence of this is that I'm guessing that the way that npins is using this in practice means that it's implicitly grabbing the latest version of lix and the module and hoping that by misinterpreting them as semver, they're matching. Unlike flakes where the module's expected lix version is encoded in the module itself via its lock file, I'm guessing that npins manages both the module and lix separately. That separate management really isn't the intent of using the module on stable versions, and is kinda fragile. The intended method is that the module should provide the lix version, and we should fix our entry points for non flakes so it does that. Also I think this question will be made somewhat obsolete by adding stable branches without having to mangle the version numbers in the tags. Obviously for HEAD the lix and lix-module are just main for both and you update both every time.

piegames commented

2025-04-13 18:44:11 +00:00

Author

Member

Just to clarify, npins doesn't manage much. The common pattern is indeed to have one pin for lix and the module. It is up to the user to take care of syncing them, and npins provides some basic tools for that.

The intended method is that the module should provide the lix version

fully agreed.

Note that implementing distro-style versioning in npins could be done, but given I won't change the current default behavior it may still lead to user confusion

Just to clarify, npins doesn't manage much. The common pattern is indeed to have one pin for lix and the module. It is up to the user to take care of syncing them, and npins provides some basic tools for that. > The intended method is that the module should provide the lix version fully agreed. Note that implementing distro-style versioning in npins could be done, but given I won't change the current default behavior it may still lead to user confusion

raito commented

2025-04-26 08:04:41 +00:00

Owner

Do we have consensus on the desired implementation? @pennae could you generate some examples of what you envision? My understanding is something like 3.0.0+2.92.0, 3.1.0+2.92.1, 3.1.1+2.92.1, etc. ?

Do we have consensus on the desired implementation? @pennae could you generate some examples of what you envision? My understanding is something like `3.0.0+2.92.0`, `3.1.0+2.92.1`, `3.1.1+2.92.1`, etc. ?

pennae commented

2025-04-26 10:38:15 +00:00

Owner

@raito you got exactly right

Rows
Columns

SemVer versioning #62