Something that I feel muddled #100833 is the number of things we call “unstable”:
packages that don’t have releases as we’re used to, thus we package whatever commit is in master at the time, like some Linux drivers¹ (e.g. rtl8192eu);
packages that do have versioned releases but the latest release is not usable by us, so we (temporarily) package an unreleased version; ipfs-cluster is a good example;
derivations tracking non-stable builds, like nixUnstable or zfsUnstable.
A good start would be to disambiguate these concepts, perhaps giving them new names.
¹: Incidentally, we should also decide if and how to include the kernel version in the pname-version combo; it’s been a while but I recall seeing a few variants.
packages that do have versioned releases but the latest release is not usable by us, so we (temporarily) package an unreleased version; ipfs-cluster is a good example;
In this case my suggestion is to use ${latestReleasedVersion}-unstable-${date of the latest usable release in yyyy-mm-dd format}.
As an example I am packaging cardboard, version 0.0.0-unstable-2021-01-21.
packages that don’t have releases as we’re used to, thus we package whatever commit is in master at the time, like some Linux drivers¹ (e.g. rtl8192eu );
They are part of the Linux kernel? Or they are maintained outside the tree? Both cases need to be cogitated.
The many times discussed problem with SemVer pre-releases is that we need to guess the next version. And I think Nix imperative upgrade logic works better with @AndersonTorres proposal.
Also, upstream may use the semvel pre-release identifiers in future releases.
For us it does not matter so much. If upstream uses, say, calVer, we just copy it. There is no ambiguity in things like fancypiler-2010-01-15-unstable-2020-12-15.
The main concern here is: parseDrvName splits the name in pname+version form, where pname goes till the first non-numerical character. According to the BDFL Eelco Dolstra, parseDrvName is not bugged
Therefore, we should follow it, not circumvent it.
About the kernel modules specifically, I would suggest to add to the end of the version string something like -linux-${kernelVersion}. Something like netcon-3.3.5-unstable-2021-12-05-linux-4.8.8.6.
Released version: pname is the project name, and version is the version as released by the upstream project.
Examples:
Unreleased branches:
If there is a released version but, for any reason, a more up-to-date source code is desired, the version is to be something like ${latest released version}-unstable-${date of the extracted source, YYYY-MM-DD format}
If there is no initial release at all, set it to 0.0.0.
Linux kernel modules: append linux-${kernel version} to version.
It is similar to derivations tracking old releases - think like GTK2 and GTK3.
Or even better, we can catch an old example: Python2 and Python3. Both Pythons came from the same source tree (biblical pun not intended), but they were released as separate projects.
We can think the same way about nixUnstable and regular nix. They are different projects from the same source tree.
A few thoughts (ignoring pragmatics/compatibility):
The existence of multiple package variants (and difficulty discriminating between them with nix-env) suggests there’s a missing (project?) abstraction. It could, for example, clarify what variants exist and either how to compose their names, or how to parse the names to distinguish them.
I guess there’s a bit of an audience conflict between the documentation here?
It’s fine/good for there to be maintainer-focused documentation that is very explicit/detailed on what all depends on the name/version and how to formulate them without breaking stuff.
I’m very skeptical that any documentation satisfying the above can be simultaneously appropriate for first-time packagers.
For the benefit of first-time packagers, it may be fruitful to treat each extra sentence/bullet needed to describe a field as a smell that it should be decomposed into simple decisions that:
have unambiguous names
do not share/overload semantics
are easy to get right without ecosystem knowledge
are automatically checked/constrained and recomposed to satisfy the ecosystem’s needs/imperatives
About the issue of newcomers, I don’t think they will be overly affected. Usually a new packager wants to insert a single package with an obvious scheming. A newcomer will hardly try to package something like VirtualBox with its modules from master branch.
On the other hand, the issues pointed out are legitimate.
I think my point wrt newcomers is that, even if the odds they’ll have something crazy to package are minimal, they still have to try and understand what the packaging guide has to say about names and versions.