Nixpkgs Conventions: Versioning, Meta Attributes, and Import From Derivation

- If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format. Example: Given a project had its latest releases `2.2` in November 2021 and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`. - If a project has no suitable preceding releases - e.g., no versions at all, or an incompatible versioning or tagging scheme - then the latest upstream version in the above schema should be `0`. Example: Given a project that has no tags or released versions at all, or applies versionless tags like `latest` or `YYYY-MM-DD-Build`, a commit authored on March 15, 2022 would have `version = "0-unstable-2022-03-15"`. Because every version of a package in Nixpkgs creates a potential maintenance burden, old versions of a package should not be kept unless there is a good reason to do so. For instance, Nixpkgs contains several versions of GCC because other packages don’t build with the latest version of GCC. Other examples are having both the latest stable and latest pre-release version of a package, or to keep several major releases of an application that differ significantly in functionality. If there is only one version of a package, its Nix expression should be named (e.g) `pkgs/by-name/xy/xyz/package.nix`. If there are multiple versions, this should be reflected in the attribute name. If you wish to share code between the Nix expressions of each version, you cannot rely upon `pkgs/by-name`'s automatic attribute creation, and must create the attributes yourself in `all-packages.nix`. See also [`pkgs/by-name/README.md`'s section on this topic](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/README.md#recommendation-for-new-packages-with-multiple-versions). ## Meta attributes The `meta` attribute set should always be placed last in the derivativion and any other "meta"-like attribute sets like `passthru` should be written before it. * `meta.description` must: * Be short, just one sentence. * Be capitalized. * Not start with the definite or an indefinite article. * Not start with the package name. * More generally, it should not refer to the package name. * Not end with a period (or any punctuation for that matter). * Provide factual information. * Avoid subjective language. * `meta.license` must be set and match the upstream license. * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`. * If in doubt, try to contact the upstream developers for clarification. * `meta.mainProgram` must be set to the name of the executable which facilitates the primary function or purpose of the package, if there is such an executable in `$bin/bin/` (or `$out/bin/`, if there is no `"bin"` output). * Packages that only have a single executable in the applicable directory above should set `meta.mainProgram`. For example, the package `ripgrep` only has a single executable `rg` under `$out/bin/`, so `ripgrep.meta.mainProgram` is set to `"rg"`. * Packages like `polkit_gnome` that have no executables in the applicable directory should not set `meta.mainProgram`. * Packages like `e2fsprogs` that have multiple executables, none of which can be considered the main program, should not set `meta.mainProgram`. * Packages which are not primarily used for a single executable do not need to set `meta.mainProgram`. * Always prefer using a hardcoded string (don't use `pname`, for example). * When in doubt, ask for reviewer input. * `meta.maintainers` must be set for new packages. See the Nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes). ## Import From Derivation [Import From Derivation](https://nixos.org/manual/nix/unstable/language/import-from-derivation) (IFD) is disallowed in Nixpkgs for performance reasons:

This chunk details Nixpkgs versioning guidelines for unstable packages, specifying formats like 'X.Y-unstable-YYYY-MM-DD' and '0-unstable-YYYY-MM-DD' for projects without prior releases. It explains that while multiple package versions are generally discouraged due to maintenance burden, exceptions exist for compatibility or significant functional differences. The document then outlines comprehensive rules for 'Meta attributes', including requirements for `meta.description` (short, capitalized, factual, no punctuation/articles/package name), `meta.license` (must be set, match upstream, default to `unfree` if absent), `meta.mainProgram` (identifying the primary executable when applicable), and `meta.maintainers` (mandatory for new packages). Finally, it states that 'Import From Derivation' (IFD) is disallowed in Nixpkgs due to performance implications.