pyrox.dev
+71
-53
CONTRIBUTING.md
+71
-53
CONTRIBUTING.md
···-The pull request template helps determine what steps have been made for a contribution so far, and will help guide maintainers on the status of a change. The motivation section of the PR should include any extra details the title does not address and link any existing issues related to the pull request.+The pull request template helps determine what steps have been made for a contribution so far, and will help guide maintainers on the status of a change.+The motivation section of the PR should include any extra details the title does not address and link any existing issues related to the pull request.···-Many Nix packages are designed to run on multiple platforms. As such, it’s important to let the maintainer know which platforms your changes have been tested on. It’s not always practical to test a change on all platforms, and is not required for a pull request to be merged. Only check the systems you tested the build on in this section.+As such, it’s important to let the maintainer know which platforms your changes have been tested on.+It’s not always practical to test a change on all platforms, and is not required for a pull request to be merged.#### Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)-Packages with automated tests are much more likely to be merged in a timely fashion because it doesn’t require as much manual testing by the maintainer to verify the functionality of the package. If there are existing tests for the package, they should be run to verify your changes do not break the tests. Tests can only be run on Linux. For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests).+Packages with automated tests are much more likely to be merged in a timely fashion because it doesn’t require as much manual testing by the maintainer to verify the functionality of the package.+If there are existing tests for the package, they should be run to verify your changes do not break the tests.+For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests).-If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still compile correctly. The `nixpkgs-review` utility can look for and build all dependencies either based on uncommitted changes with the `wip` option or specifying a GitHub pull request number.+If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still compile correctly.+The `nixpkgs-review` utility can look for and build all dependencies either based on uncommitted changes with the `wip` option or specifying a GitHub pull request number.···-It’s important to test any executables generated by a build when you change or create a package in nixpkgs. This can be done by looking in `./result/bin` and running any files in there, or at a minimum, the main executable for the package. For example, if you make a change to texlive, you probably would only check the binaries associated with the change you made rather than testing all of them.+It’s important to test any executables generated by a build when you change or create a package in nixpkgs.+This can be done by looking in `./result/bin` and running any files in there, or at a minimum, the main executable for the package.+For example, if you make a change to texlive, you probably would only check the binaries associated with the change you made rather than testing all of them.-The last checkbox is about whether it fits the guidelines in this `CONTRIBUTING.md` file. This document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc... Everyone should read and understand the standards the community has for contributing before submitting a pull request.+This document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc...+Everyone should read and understand the standards the community has for contributing before submitting a pull request.+From time to time, changes between branches must be rebased, for example, if the number of new rebuilds they would cause is too large for the target branch.+In the following example, we assume that the current branch, called `feature`, is based on `master`, and we rebase it onto the merge base between `master` and `staging` so that the PR can be retargeted to `staging`.+The example uses `upstream` as the remote for `NixOS/nixpkgs.git` while `origin` is the remote you are pushing to.···+The syntax `upstream/staging...` is equivalent to `upstream/staging...HEAD` and stands for the merge base between `upstream/staging` and `HEAD` (hence between `upstream/staging` and `upstream/master`).+Then change the base branch in the GitHub PR using the *Edit* button in the upper right corner, and switch from `master` to `staging`.+*After* the PR has been retargeted it might be necessary to do a final rebase onto the target branch, to resolve any outstanding merge conflicts.···> The following section is a draft, and the policy for reviewing is still being discussed in issues such as [#11166](https://github.com/NixOS/nixpkgs/issues/11166) and [#20836](https://github.com/NixOS/nixpkgs/issues/20836).-The Nixpkgs project receives a fairly high number of contributions via GitHub pull requests. Reviewing and approving these is an important task and a way to contribute to the project.-The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger. Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue. GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests. We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone).+The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger.+Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue.+GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests.+We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone).-When reviewing a pull request, please always be nice and polite. Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work.+Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work.-GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.+GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments.+The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.···Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.-All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview].If a pull request contains documentation changes that might require feedback from the documentation team, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on the pull request.-If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic. They will give you information about the reviewing process. The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints.+If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic.+The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints.Container system, boot system and library changes are some examples of the pull requests fitting this category.-To streamline automated updates, leverage the nixpkgs-merge-bot by simply commenting `@NixOS/nixpkgs-merge-bot merge`. The bot will verify if the following conditions are met, refusing to merge otherwise:+To streamline automated updates, leverage the nixpkgs-merge-bot by simply commenting `@NixOS/nixpkgs-merge-bot merge`.-Further, nixpkgs-merge-bot will ensure all ofBorg checks (except the Darwin-related ones) are successfully completed before merging the pull request. Should the checks still be underway, the bot patiently waits for ofBorg to finish before attempting the merge again.+Further, nixpkgs-merge-bot will ensure all ofBorg checks (except the Darwin-related ones) are successfully completed before merging the pull request.+Should the checks still be underway, the bot patiently waits for ofBorg to finish before attempting the merge again.For other pull requests, please see [I opened a PR, how do I get it merged?](#i-opened-a-pr-how-do-i-get-it-merged).+In case the PR is stuck waiting for the original author to apply a trivial change (a typo, capitalisation change, etc.) and the author allowed the members to modify the PR, consider applying it yourself (or commit the existing review suggestion).+You should pay extra attention to make sure the addition doesn't go against the idea of the original PR and would not be opposed by the author.The following paragraphs about how to deal with unactive contributors is just a proposition and should be modified to what the community agrees to be the right policy.···It works by directing commits that cause [mass rebuilds][mass-rebuild] to a separate `staging` branch that isn't directly built by Hydra.Regularly, the `staging` branch is _manually_ merged into a `staging-next` branch to be built by Hydra using the [`nixpkgs:staging-next` jobset](https://hydra.nixos.org/jobset/nixpkgs/staging-next).+The `staging-next` branch should then only receive changes that fix Hydra builds; **for anything else, ask the [Staging room](https://matrix.to/#/#staging:nixos.org) first**.Once it is verified that there are no major regressions, it is merged into `master` using [a pull request](https://github.com/NixOS/nixpkgs/pulls?q=head%3Astaging-next).By keeping the `staging-next` branch separate from `staging`, this batching does not block developers from merging changes into `staging`.···-- If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`.+- If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case.See [Squashing Commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) for additional information.- For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message).······-In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.+In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made.+While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.-Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.+Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog.+Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.···-Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.+Names of files and directories should be in lowercase, with dashes between words — not in camel case.+CI [enforces](./.github/workflows/check-format.yml) all Nix files to be formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).···+If you're starting your editor in `nix-shell` or `nix develop`, you can also set it up to automatically format the file with `treefmt` on save.+If you have any problems with formatting, please ping the [formatting team](https://nixos.org/community/teams/formatting/) via [@NixOS/nix-formatting](https://github.com/orgs/NixOS/teams/nix-formatting).- Set up [editorconfig](https://editorconfig.org/) for your editor, such that [the settings](./.editorconfig) are automatically applied.-- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).+Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).······- Improve skimmability: use a simple descriptive PR title (details go in commit titles) outlining _what_ is done and _why_.-- Wait. Reviewers frequently browse open PRs and may happen to run across yours and take a look.-- Get non-committers to review/approve. Many committers filter open PRs for low-hanging fruit that are already been reviewed.- [@-mention](https://github.blog/news-insights/mention-somebody-they-re-notified/) someone and ask them nicely- Post in one of the channels made for this purpose if there has been no activity for at least one week- The current "PRs ready for review" or "PRs already reviewed" threads in the [NixOS Discourse](https://discourse.nixos.org/c/dev/14) (of course choose the one that applies to your situation)···Don't be afraid of asking for advice if you're uncertain how to do that, others have likely fixed such issues dozens of times and can help you out.Your PR is unlikely to be merged if it has a known issue and it is the purpose of CI to alert you aswell as reviewers to these issues.-ofBorg builds can often get stuck, particularly in PRs targeting `staging` and in builders for the Darwin platform. Reviewers will know how to handle them or when to ignore them.+ofBorg builds can often get stuck, particularly in PRs targeting `staging` and in builders for the Darwin platform.If there is a build failure however and it happened due to a package related to your change, you need to investigate it of course.
+20
-36
README.md
+20
-36
README.md
···<a href="https://opencollective.com/nixos"><img src="https://opencollective.com/nixos/tiers/supporter/badge.svg?label=supporters&color=brightgreen" alt="Open Collective supporters" /></a>+[Nixpkgs](https://github.com/nixos/nixpkgs) is a collection of over 120,000 software packages that can be installed with the [Nix](https://nixos.org/nix/) package manager.···+The sources of all official Nix-related projects are in the [NixOS organization on GitHub](https://github.com/NixOS/).···+Nixpkgs and NixOS are built and tested by our continuous integration system, [Hydra](https://hydra.nixos.org/).* [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)* [Continuous package builds for the NixOS 25.05 release](https://hydra.nixos.org/jobset/nixos/release-25.05)* [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)* [Tests for the NixOS 25.05 release](https://hydra.nixos.org/job/nixos/release-25.05/tested#tabs-constituents)+When successful build and test criteria are met, the Nixpkgs expressions are distributed via [Nix channels](https://nix.dev/manual/nix/stable/command-ref/nix-channel.html).+While thousands of open issues and pull requests might seem a lot at first, it helps consider it in the context of the scope of the project.+Nixpkgs describes how to build tens of thousands of pieces of software and implements a Linux distribution.+The [GitHub Insights](https://github.com/NixOS/nixpkgs/pulse) page gives a sense of the project activity.+For more information about contributing to the project, please visit the [contributing page](CONTRIBUTING.md).+The infrastructure for NixOS and related projects is maintained by a nonprofit organization, the [NixOS Foundation](https://nixos.org/nixos/foundation.html).+To ensure the continuity and expansion of the NixOS infrastructure, we are looking for donations to our organization.+You can donate to the NixOS foundation through [SEPA bank transfers](https://nixos.org/donate.html) or by using Open Collective:<a href="https://opencollective.com/nixos#support"><img src="https://opencollective.com/nixos/tiers/supporter.svg?width=890" /></a>···+MIT license does not apply to the packages built by Nixpkgs, merely to the files in this repository (the Nix expressions, build scripts, NixOS modules, etc.).+It also might not apply to patches included in Nixpkgs, which may be derivative works of the packages to which they apply.
+21
-10
doc/README.md
+21
-10
doc/README.md
···Once you have a successful build, you can open the relevant HTML (path mentioned above) in a browser along with the anchor, and observe the redirection.-Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload. This is because browsers do not re-run client JS code when only the anchor has changed.+Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload.As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.-Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:+Additional syntax extensions are available, all of which can be used in NixOS option documentation.···-Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).+These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:···-If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.+If you **omit a link text** for a link pointing to a section, the text will be substituted automatically.This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).-Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.+Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.-If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).+The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).···-This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.+This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point).+Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.···-- Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.-- Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.- _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.···-Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).+Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
+1
-2
lib/deprecated/README.md
+1
-2
lib/deprecated/README.md
···-Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided,+Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided, while some functions *may still be needed*.
+4
-2
lib/fileset/README.md
+4
-2
lib/fileset/README.md
···-- (-) This is unnecessarily strict, because the purpose of the base path is to track the directory under which files _could_ be in the file set. It should be as long as possible.+- (-) This is unnecessarily strict, because the purpose of the base path is to track the directory under which files _could_ be in the file set.All files contained in `intersection ./foo ./foo/bar` will be under `./foo/bar` (never just under `./foo`), and `intersection ./foo ./bar` will never contain any files (never under `./.`).This would lead to `toSource` having to unexpectedly throw errors for cases such as `toSource { root = ./foo; fileset = intersect ./foo base; }`, where `base` may be `./bar` or `./.`.- (-) There is no benefit to the user, since base path is not directly exposed in the interface···E.g. when trying to prevent `./secret` from being imported, a typo like `difference ./. ./sercet` would import it regardless.- (+) `difference ./. (maybeMissing ./does-not-exist)` can be used to do this more explicitly.-- (+) `difference ./. (difference ./foo ./foo/bar)` should report an error when `./foo/bar` does not exist ("double negation"). Unfortunately, the current internal representation does not lend itself to a behavior where both `difference x ./does-not-exists` and double negation are handled and checked correctly.+- (+) `difference ./. (difference ./foo ./foo/bar)` should report an error when `./foo/bar` does not exist ("double negation").+Unfortunately, the current internal representation does not lend itself to a behavior where both `difference x ./does-not-exists` and double negation are handled and checked correctly.
+41
-18
lib/path/README.md
+41
-18
lib/path/README.md
···-The purpose of this library is to process [filesystem paths]. It does not read files from the filesystem.···As an extension of the path value type, it inherits the same intended use cases and limitations:-- A path implicitly imports the referenced files into the Nix store when interpolated to a string. Therefore paths are not suitable to access files at build- or run-time, as you risk importing the path from the evaluation system instead.+- A path implicitly imports the referenced files into the Nix store when interpolated to a string.+Therefore paths are not suitable to access files at build- or run-time, as you risk importing the path from the evaluation system instead.-- Absolute paths are represented with the Nix [path value type]. Nix automatically normalises these paths.-- Subpaths are represented with the [string value type] since path value types don't support relative paths. This library normalises these paths as safely as possible. Absolute paths in strings are not supported.+- Subpaths are represented with the [string value type] since path value types don't support relative paths.It is a stricter form of a relative path, notably [without support for `..` components][parents] since those could escape the base directory.···This library is designed to be as safe and intuitive as possible, throwing errors when operations are attempted that would produce surprising results, and giving the expected result otherwise.-This library is designed to work well as a dependency for the `lib.filesystem` and `lib.sources` library components. Contrary to these library components, `lib.path` does not read any paths from the filesystem.+This library is designed to work well as a dependency for the `lib.filesystem` and `lib.sources` library components.- `dirOf path` returns the path to the parent directory of `path`, unless `path` is the filesystem root, in which case `path` is returned.···-- (+) In shells, just running `foo` as a command wouldn't execute the file `foo`, whereas `./foo` would execute the file. In contrast, `foo/bar` does execute that file without the need for `./`. This can lead to confusion about when a `./` needs to be prefixed. If a `./` is always included, this becomes a non-issue. This effectively then means that paths don't overlap with command names.+- (+) In shells, just running `foo` as a command wouldn't execute the file `foo`, whereas `./foo` would execute the file.-- (+) Using paths in command line arguments could give problems if not escaped properly, e.g. if a path was `--version`. This is not a problem with `./--version`. This effectively then means that paths don't overlap with GNU-style command line options.+- (+) Using paths in command line arguments could give problems if not escaped properly, e.g. if a path was `--version`.- (-) `./` is not required to resolve relative paths, resolution always has an implicit `./` as prefix.···-- (-) But only if you give it an argument of `.`. If you give it the argument `some-directory`, it won't prefix that.···- (+) `./` would be inconsistent with [the decision to not persist trailing slashes][trailing-slashes].- (+) `.` can be interpreted as a shell command (it's a builtin for sourcing files in `bash` and `zsh`).-- (+) `.` would be the only path without a `/`. It could not be used as a Nix path expression, since those require at least one `/` to be parsed as such.+It could not be used as a Nix path expression, since those require at least one `/` to be parsed as such.As inputs all three variants are supported for subpaths (and we can't do anything about absolute paths)···-Considering: Paths should be as safe to use as possible. We should generate string outputs in the library and not encourage users to do that themselves.+We should generate string outputs in the library and not encourage users to do that themselves.-- (+) It's simpler for the users of the library. One doesn't have to convert a path a string before it can be used.- (+) Naively converting the list representation to a string with `concatStringsSep "/"` would break for `[]`, requiring library users to be more careful.- (+) It doesn't encourage people to do their own path processing and instead use the library.With a list representation it would seem easy to just use `lib.lists.init` to get the parent directory, but then it breaks for `.`, which would be represented as `[ ]`.···-Decision: `..` path components in string paths are not supported, neither as inputs nor as outputs. Hence, string paths are called subpaths, rather than relative paths.+Decision: `..` path components in string paths are not supported, neither as inputs nor as outputs.- (+) If we wanted relative paths to behave according to the "physical" interpretation (as a directory tree with relations between nodes), it would require resolving symlinks, since e.g. `foo/..` would not be the same as `.` if `foo` is a symlink.-- (-) The "logical" interpretation is also valid (treating paths as a sequence of names), and is used by some software. It is simpler, and not using symlinks at all is safer.+- (-) The "logical" interpretation is also valid (treating paths as a sequence of names), and is used by some software.-- (-) We could just not handle such cases, e.g. `equals "foo" "foo/bar/.. == false`. The paths are different, we don't need to check whether the paths point to the same thing.-- (+) Assume we said `relativeTo /foo /bar == "../bar"`. If this is used like `/bar/../foo` in the end, and `bar` turns out to be a symlink to somewhere else, this won't be accurate.+If this is used like `/bar/../foo` in the end, and `bar` turns out to be a symlink to somewhere else, this won't be accurate.- (-) We could decide to not support such ambiguous operations, or mark them as such, e.g. the normal `relativeTo` will error on such a case, but there could be `extendedRelativeTo` supporting that.- (+) If we can convincingly argue that all such use cases are better done e.g. with runtime tools, the library not supporting it can nudge people towards using those.···-- (+) It allows normalisations to be unique, in that there's only a single normalisation for the same path. If trailing slashes were preserved, both `foo/bar` and `foo/bar/` would be valid but different normalisations for the same path.+- (+) It allows normalisations to be unique, in that there's only a single normalisation for the same path.+If trailing slashes were preserved, both `foo/bar` and `foo/bar/` would be valid but different normalisations for the same path.- (+) Nix itself doesn't support trailing slashes when parsing and doesn't preserve them when appending paths.- (-) [Rust's std::path](https://doc.rust-lang.org/std/path/index.html) does preserve them during [construction](https://doc.rust-lang.org/std/path/struct.Path.html#method.new).···-Considering: Subpaths are used as inputs for some functions. Using them for outputs, too, makes the library more consistent and composable.···- (-) It is less efficient when the components are needed, because after creating the normalised subpath string, it will have to be parsed into components again- (+) Alternatively if necessary, versions of these functions that return components could later still be introduced.-- (+) It makes the path library simpler because there's only two types (paths and subpaths). Only `lib.path.subpath.components` can be used to get a list of components.And once we have a list of component strings, `lib.lists` and `lib.strings` can be used to operate on them.For completeness, `lib.path.subpath.join` allows converting the list of components back to a subpath.
+78
-129
maintainers/README.md
+78
-129
maintainers/README.md
···+Unlike other packaging ecosystems, the maintainer doesn't have exclusive control over the packages and modules they maintain.+The main responsibility of a maintainer is to keep the packages they maintain in a functioning state, and keep up with updates.+We also allow other non-maintainer committers to merge changes to the package, provided enough time and priority has been given to the maintainer.-changes not endorsed by a package maintainer (which may be themselves). This should leave enough time+For most packages, we expect committers to wait at least a week before merging changes not endorsed by a package maintainer (which may be themselves).+A critical package is one that causes mass-rebuild, or where an author is listed in the [`OWNERS`](../ci/OWNERS) file.-In case of critical security updates, the [security team](https://nixos.org/community/teams/security) might override these+In case of critical security updates, the [security team](https://nixos.org/community/teams/security) might override these heuristics in order to get the fixes in as fast as possible.+In order to do so, add yourself to the [`maintainer-list.nix`](./maintainer-list.nix), and then to the desired package's `meta.maintainers` list, and send a PR with the changes.+If you're adding yourself as a maintainer as part of another PR (in which you become a maintainer of a package, for example), make your change to+We would typically look at it if we notice that the author hasn't reacted to package-related notifications for more than 3 months.+Removing the maintainer happens by making a PR on the package, adding that person as a reviewer, and then waiting a week for a reaction.-maintainer(s) by trying to correlate the files the PR touches with the packages that need rebuilding.+When a pull request is made against a package, nixpkgs CI will notify the appropriate maintainer(s) by trying to correlate the files the PR touches with the packages that need rebuilding.-Maintainers can also invoke the [nixpkgs-merge-bot](https://github.com/nixos/nixpkgs-merge-bot)-to merge pull requests targeting packages they are the maintainer of, which satisfy the current-security [constraints](https://github.com/NixOS/nixpkgs-merge-bot/blob/main/README.md#constraints).+Maintainers can also invoke the [nixpkgs-merge-bot](https://github.com/nixos/nixpkgs-merge-bot) to merge pull requests targeting packages they are the maintainer of, which satisfy the current security [constraints](https://github.com/NixOS/nixpkgs-merge-bot/blob/main/README.md#constraints).Examples: [#397273](https://github.com/NixOS/nixpkgs/pull/397273#issuecomment-2789382120) and [#377027](https://github.com/NixOS/nixpkgs/pull/377027#issuecomment-2614510869)New maintainers will automatically get invited to join the [NixOS/nixpkgs-maintainers](https://github.com/orgs/NixOS/teams/nixpkgs-maintainers) GitHub team.···[zh.fail](https://zh.fail/failed/overview.html) tracks all package build failures on `master` grouped by maintainer.-[asymmetric/nixpkgs-update-notifier](https://github.com/asymmetric/nixpkgs-update-notifier) is a matrix-bot that scrapes the [nixpkgs-update logs](https://nixpkgs-update-logs.nix-community.org/) and notifies+[asymmetric/nixpkgs-update-notifier](https://github.com/asymmetric/nixpkgs-update-notifier) is a matrix bot that scrapes the [nixpkgs-update logs](https://nixpkgs-update-logs.nix-community.org/) and notifies you if nixpkgs-update/@r-ryantm fails to update any of the packages you've subscribed to.[repology.org](https://repology.org) tracks and compares the versions of packages between various package repositories, letting you know what packages may be out of date or insecure.-You can view which packages a specific maintainer maintains and subscribe to updates with atom/rss. Example: [repology.org/maintainer/pbsds](https://repology.org/maintainer/pbsds%40hotmail.com).+You can view which packages a specific maintainer maintains and subscribe to updates with atom/rss.-[nixpk.gs/pr-tracker](https://nixpk.gs/pr-tracker.html) and [nixpkgs-tracker.ocfox.me](https://nixpkgs-tracker.ocfox.me/)+[nixpk.gs/pr-tracker](https://nixpk.gs/pr-tracker.html) and [nixpkgs-tracker.ocfox.me](https://nixpkgs-tracker.ocfox.me/) can visualize the release status of any nixpkgs pull request.+When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the following checks should be performed:+First, validate that the commit adding the maintainer is signed by the key the maintainer listed.+If the commit is not signed or it is signed by a different user, ask them to either recommit using that key or to remove their key information.···+and validate that there is a `Good signature` and the printed key matches the user's submitted key.+Note: GitHub's "Verified" label does not display the user's full key fingerprint, and should not be used for validating the key matches.+- If the user has specified a `github` account name, ensure they have also specified a `githubId` and verify the two match.+People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer.···+Then, visit the URL `https://api.github.com/users/ghost` and validate that the `id` field matches the provided `githubId`.+Feel free to create a new maintainer team in [`team-list.nix`](./team-list.nix) when a group is collectively responsible for a collection of packages.+For example, some teams will represent a business or other group which wants to carefully track its members.+When reviewing changes to a team, read the team's scope and the context around the member list for indications about the team's membership policy.+If the team lists no specific membership policy, feel free to merge changes to the team after giving the existing members a few days to respond.+*Important:* If a team says it is a closed group, do not merge additions to the team without an approval by at least one existing member.+Various utility scripts, which are mainly useful for nixpkgs maintainers, are available under `./scripts/`.-To streamline autoupdates, leverage the nixpkgs-merge-bot by commenting `@NixOS/nixpkgs-merge-bot merge` if the package resides in pkgs-by-name, the commenter is among the package maintainers, and the pull request author is @r-ryantm or a Nixpkgs committer. The bot ensures that all ofborg checks, except for darwin, are successfully completed before merging the pull request. Should the checks still be underway, the bot patiently waits for ofborg to finish before attempting the merge again.+To streamline autoupdates, leverage the nixpkgs-merge-bot by commenting `@NixOS/nixpkgs-merge-bot merge` if the package resides in pkgs-by-name, the commenter is among the package maintainers, and the pull request author is @r-ryantm or a Nixpkgs committer.+The bot ensures that all ofborg checks, except for darwin, are successfully completed before merging the pull request.+Should the checks still be underway, the bot patiently waits for ofborg to finish before attempting the merge again.+If a commit breaks evaluation, it will affect Ofborg evaluation results in other pull requests and block Hydra CI, thus introducing chaos to our workflow.+One approach to avoid merging such problematic changes is to wait for successful Ofborg evaluation.+Additionally, using tools like [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) can help spot issues early, before Ofborg finishes evaluation.+In general breaking changes to `master` and `staging` branches are permitted, as long as they are documented in the release notes.+Though restrictions might apply towards the end of a NixOS release cycle, due to our feature freeze mechanism.+This is to avoid large-scale breakages shortly before and during a Zero Hydra Failures (ZHF) campaign.+> These are some example changes and if they are considered a breaking change during a freeze period:+> Assuming this package follows semantic versioning and none of its dependent packages fail to build because of this change, it can be safely merged.+> Otherwise, if it can be confirmed that there is no major change in its functionality or API, but only adding new features or fixing bugs, it can also be merged.+> If this PR removes a leaf package or the removal doesn't otherwise break other packages, it can be merged.+> As long as this PR replaces all references to the old attribute name with the new name and adds an alias, it can be merged.+> If this PR would trigger many rebuilds and/or target `staging`, it should probably be delayed until after the freeze-period is over.+> Alternatively, if this PR is for a popular package and doesn't cause many rebuilds, it should also be delayed to reduce risk of breakage.+> If a PR includes important changes, such as security fixes, it should be brought up to release managers.+> If this PR adjusts the type, default value or effect of options in the NixOS module, so that users must rewrite their configuration to keep the current behavior unchanged, it should not be merged, as we don't have enough time to collect user feedback and avoid possible breakage.+> However, it should be accepted if the current behavior is considered broken and is fixed by the PR.
+6
-13
maintainers/scripts/README.md
+6
-13
maintainers/scripts/README.md
···+This folder contains various executable scripts for nixpkgs maintainers, and supporting data or nixlang files as needed.+`get-maintainer.sh [selector] value` returns a JSON object describing a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`.+This allows looking up a maintainer's attrset (including GitHub and Matrix handles, email address etc.) based on any of their handles, more correctly and···+attributes of the maintainer's object, matched exactly; see [`maintainer-list.nix`] for the fields' definition.+Outputs a JSON object on stdout mapping GitHub usernames to the attributes that they would be getting pinged for.···-`sha-to-sri.py path ...` (atomically) rewrites hash attributes (named `hash` or `sha(1|256|512)`)+`sha-to-sri.py path ...` (atomically) rewrites hash attributes (named `hash` or `sha(1|256|512)`) into the SRI format: `hash = "{hash name}-{base64 encoded value}"`.
+1
-2
maintainers/scripts/auto-rebase/README.md
+1
-2
maintainers/scripts/auto-rebase/README.md
···-The [`./run.sh` script](./run.sh) in this directory rebases the current branch onto a target branch,-while automatically resolving merge conflicts caused by marked commits in [`.git-blame-ignore-revs`](../../../.git-blame-ignore-revs).+The [`./run.sh` script](./run.sh) in this directory rebases the current branch onto a target branch, while automatically resolving merge conflicts caused by marked commits in [`.git-blame-ignore-revs`](../../../.git-blame-ignore-revs).
+24
-42
maintainers/scripts/bootstrap-files/README.md
+24
-42
maintainers/scripts/bootstrap-files/README.md
···+Currently `nixpkgs` builds most of it's packages using bootstrap seed binaries (without the reliance on external inputs):+- `bootstrap-tools`: an archive with the compiler toolchain and other helper tools enough to build the rest of the `nixpkgs`.+On `linux` it's just `busybox`, on `darwin` and `freebsd` it is unpack.nar.xz which contains the binaries and script needed to unpack the tools.+Bootstrap files should always be fetched from hydra and uploaded to `tarballs.nixos.org` to guarantee that all the binaries were built from the code committed into `nixpkgs` repository.···$ maintainers/scripts/bootstrap-files/refresh-tarballs.bash --commit --targets=i686-unknown-linux-gnu+For `riscv64-unknown-linux-gnu` the `/etc/nixos/configuration.nix` entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`.+3. Propose the commit as a PR to update bootstrap tarballs, tag people who can help you test the updated architecture and once reviewed tag `@lovesegfault` to upload the tarballs.+4. Add your new target to `maintainers/scripts/bootstrap-files/refresh-tarballs.bash` around `CROSS_TARGETS=()`.+5. Add your new target to `pkgs/stdenv/linux/default.nix` and follow standard bootstrap seed update procedure above.+- natively built `stdenvBootstrapTools.build` hydra jobs in [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs) jobset.+- cross-built by `bootstrapTools.build` hydra jobs in [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs) jobset.···+The `.build` job contains `/on-server/` subdirectory with binaries to be uploaded to `tarballs.nixos.org`.
+9
-6
nixos/README.md
+9
-6
nixos/README.md
···-You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`). And do `sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast`.+You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`).···-When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.+Grub installations cannot be rolled back, hence changes may break people’s installations forever.+For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.-Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options.
+2
-1
nixos/doc/manual/README.md
+2
-1
nixos/doc/manual/README.md
+114
-48
pkgs/README.md
+114
-48
pkgs/README.md
···-We welcome new contributors of new packages to Nixpkgs, arguably the greatest software database known. However, each new package comes with a cost for the maintainers, Continuous Integration, caching servers and users downloading Nixpkgs.+We welcome new contributors of new packages to Nixpkgs, arguably the greatest software database known.+However, each new package comes with a cost for the maintainers, Continuous Integration, caching servers and users downloading Nixpkgs.-* Is the package ready for general use? We don't want to include projects that are too immature or are going to be abandoned immediately. In case of doubt, check with upstream.-* Does the project have a clear license statement? Remember that software is unfree by default (all rights reserved), and merely providing access to the source code does not imply its redistribution. In case of doubt, ask upstream.-* How realistic is it that it will be used by other people? It's good that nixpkgs caters to various niches, but if it's a niche of 5 people it's probably too small. A good estimate is checking upstream issues and pull requests, or other software repositories. Library packages should have at least one dependent.-* Is the software actively maintained upstream? Especially packages that are security-critical, rely on fast-moving dependencies, or affect data integrity should see regular maintenance.-* Are you willing to maintain the package? You should care enough about the package to be willing to keep it up and running for at least one complete Nixpkgs' release life-cycle.+We don't want to include projects that are too immature or are going to be abandoned immediately.+Remember that software is unfree by default (all rights reserved), and merely providing access to the source code does not imply its redistribution.+It's good that nixpkgs caters to various niches, but if it's a niche of 5 people it's probably too small.+Especially packages that are security-critical, rely on fast-moving dependencies, or affect data integrity should see regular maintenance.+You should care enough about the package to be willing to keep it up and running for at least one complete Nixpkgs' release life-cycle.* In case you are not able to maintain the package you wrote, you can seek someone to fill that role, effectively adopting the package.-Special care has to be taken with security-critical software components. Because entries in the Nix store are inert and do nothing by themselves, packages should be considered by their intended use, e.g. when used together with a NixOS module.+Because entries in the Nix store are inert and do nothing by themselves, packages should be considered by their intended use, e.g. when used together with a NixOS module.* Any package that immediately would need to be tagged with `meta.knownVulnerabilities` is unlikely to be fit for nixpkgs.-* Packages typically used with untrusted data should have a maintained and responsible upstream. For example:-* Any package which does not follow upstream security policies should be considered vulnerable. In particular, packages that vendor or fork web engines like Blink, Gecko or Webkit need to keep up with the frequent updates of those projects.-* Any security-critical fast-moving package such as Chrome or Firefox (or their forks) must have at least one active committer among the maintainers. This ensures no critical fixes are delayed unnecessarily, endangering unsuspecting users.+* Packages typically used with untrusted data should have a maintained and responsible upstream.+* Any package which does not follow upstream security policies should be considered vulnerable.+In particular, packages that vendor or fork web engines like Blink, Gecko or Webkit need to keep up with the frequent updates of those projects.+* Any security-critical fast-moving package such as Chrome or Firefox (or their forks) must have at least one active committer among the maintainers.* Data (such as archives or rich documents) commonly shared over untrusted channels (e.g. email) is untrusted.* Applications in the Unix authentication stack such as PAM/D-Bus modules or SUID binaries should be considered carefully, and should have a maintained and responsible upstream.···* These aspects are sometimes hard to verify, in which case an upstream that is not known to be irresponsible should be considered as responsible.-* Source-available software should be built from source where possible. Binary blobs risk supply chain attacks and vendored outdated libraries.······-3. Create a `package.nix` file in the package directory, containing a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store.+3. Create a `package.nix` file in the package directory, containing a Nix expression — a piece of code that describes how to build the package.+In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store.···You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done, some of which are also using the [category hierarchy](#category-hierarchy).-- GNU Hello: [`pkgs/by-name/he/hello/package.nix`](./by-name/he/hello/package.nix). Trivial package, which specifies some `meta` attributes which is good practice.-- GNU cpio: [`pkgs/by-name/cp/cpio/package.nix`](./by-name/cp/cpio/package.nix). Also a simple package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`.-- GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp`](development/libraries/gmp). Also done by the generic builder, but has a dependency on `m4`.+- GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp`](development/libraries/gmp).-- Pan, a GTK-based newsreader: [`pkgs/by-name/pa/pan/package.nix`](./by-name/pa/pan/package.nix). Has an optional dependency on `gspell`, which is only built if `spellCheck` is `true`.+- Pan, a GTK-based newsreader: [`pkgs/by-name/pa/pan/package.nix`](./by-name/pa/pan/package.nix).-- Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.+- Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](servers/http/apache-httpd/2.4.nix).+A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.-- buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](applications/networking/browsers/firefox/common.nix). A reusable build function for Firefox, Thunderbird and Librewolf.+- buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](applications/networking/browsers/firefox/common.nix).-- JDiskReport, a Java utility: [`pkgs/by-name/jd/jdiskreport/package.nix`](./by-name/jd/jdiskreport/package.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.+- JDiskReport, a Java utility: [`pkgs/by-name/jd/jdiskreport/package.nix`](./by-name/jd/jdiskreport/package.nix).-- XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](top-level/perl-packages.nix) (search for the `XMLSimple` attribute). Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.+- XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](top-level/perl-packages.nix) (search for the `XMLSimple` attribute).+Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.-- Discord Game SDK: [`pkgs/by-name/di/discord-gamesdk/package.nix`](./by-name/di/discord-gamesdk/package.nix). Shows how binary-only packages can be supported. In particular, the `autoPatchelfHook` is used to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.+- Discord Game SDK: [`pkgs/by-name/di/discord-gamesdk/package.nix`](./by-name/di/discord-gamesdk/package.nix).+In particular, the `autoPatchelfHook` is used to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.···-where `some-package` should be the package name. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.+You may want to add the flag `-K` to keep the temporary build directory in case something fails.···-The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _should not_, _recommended_, _may_, and _optional_ in this section are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). Only _emphasized_ words are to be interpreted in this way.+The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _should not_, _recommended_, _may_, and _optional_ in this section are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).-- The `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`.- The attribute name used for the package in the [`pkgs/by-name` structure](./by-name/README.md) or in [`all-packages.nix`](./top-level/all-packages.nix), and when passing it as a dependency in recipes.-Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the attribute name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.+For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the attribute name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.···-- If the `pname` starts with a digit, the attribute name _should_ be prefixed with an underscore. Otherwise the attribute name _should not_ be prefixed with an underline.+- If the `pname` starts with a digit, the attribute name _should_ be prefixed with an underscore.···-- It _must_ start with a digit. This is required for backwards-compatibility with [how `nix-env` parses derivation names](https://nix.dev/manual/nix/latest/command-ref/nix-env#selectors).+This is required for backwards-compatibility with [how `nix-env` parses derivation names](https://nix.dev/manual/nix/latest/command-ref/nix-env#selectors).-- 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.+- 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.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"`.···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.+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).+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 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.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 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`.···When using the `patches` parameter to `mkDerivation`, make sure the patch name clearly describes the reason for the patch, or add a comment.-> The version of the package does not need to be changed just because a patch is applied. Declarative package installations don't depend on the version, while imperative `nix-env` installations can use [`upgrade --eq/leq/--always`](https://nix.dev/manual/nix/2.25/command-ref/nix-env/upgrade#flags).+> Declarative package installations don't depend on the version, while imperative `nix-env` installations can use [`upgrade --eq/leq/--always`](https://nix.dev/manual/nix/2.25/command-ref/nix-env/upgrade#flags).-The following describes two ways to include the patch. Regardless of how the patch is included, you _must_ ensure its purpose is clear and obvious. This enables other maintainers to more easily determine when old patches are no longer required. Typically, you can improve clarity with carefully considered filenames, attribute names, and/or comments; these should explain the patch's _intention_. Additionally, it may sometimes be helpful to clarify _how_ it resolves the issue. For example: _"fix gcc14 build by adding missing include"_.+This enables other maintainers to more easily determine when old patches are no longer required.+Typically, you can improve clarity with carefully considered filenames, attribute names, and/or comments; these should explain the patch's _intention_.···> This is the case if the patch contains a line similar to `index 0c97fcc35..f533e464a 100644`.> Depending on the patch source it is possible to expand the commit hash, in which case using `fetchpatch2` is acceptable (e.g. GitHub supports appending `?full_index=1` to the URL, as seen above).-If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch2`. Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details.+If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch2`.+Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details.-When adding patches in this manner you should be reasonably sure that the used URL is stable. Patches referencing open pull requests will change when the PR is updated and code forges (such as GitHub) usually garbage collect commits that are no longer reachable due to rebases/amends.+Patches referencing open pull requests will change when the PR is updated and code forges (such as GitHub) usually garbage collect commits that are no longer reachable due to rebases/amends.···1. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher`-1. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/applications/editors/vim/plugins/aliases.nix`. Package sets typically do not have aliases, so we can't add them there.)+1. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/applications/editors/vim/plugins/aliases.nix`.···The throw message should explain in short why the package was removed for users that still have it installed.-1. Test if the changes introduced any issues by running `nix-env -qaP -f . --show-trace`. It should show the list of packages without errors.-1. Commit the changes. Explain again why the package was removed. If it was declared discontinued upstream, add a link to the source.$ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix···This is how the pull request looks like in this case: [https://github.com/NixOS/nixpkgs/pull/116470](https://github.com/NixOS/nixpkgs/pull/116470)···-* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs. They exercise both NixOS modules and the packaged programs used within them. For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.-* Nix **package tests** are a lightweight alternative to NixOS module tests. They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.+* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs.+For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.+They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.* The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).···-- [`UPDATE_NIX_ATTR_PATH`] – attribute path the `update.nix` discovered the package on (or the package's specified `attrPath` when available). Example: `pantheon.elementary-terminal`+- [`UPDATE_NIX_ATTR_PATH`] – attribute path the `update.nix` discovered the package on (or the package's specified `attrPath` when available).> An update script will be usually run from the root of the Nixpkgs repository, but you should not rely on that.···-A package update is the most trivial and common type of pull request. These pull requests mainly consist of updating the version part of the package name and the source hash.+These pull requests mainly consist of updating the version part of the package name and the source hash.···- The continuous integration system will make GitHub notify users based on the submitted changes, but it can happen that it misses some of the package maintainers.- Ensure that the meta field information [fits the guidelines](#meta-attributes) and is correct:- License can change with version updates, so it should be checked to match the upstream license.-- If the package has no maintainer, a maintainer must be set. This can be the update submitter or a community member that accepts to take maintainership of the package.+This can be the update submitter or a community member that accepts to take maintainership of the package.- If switching to a fork, check with external sources like other package repositories for community consensus.···- The second command fetches the pull request changes, `PRNUMBER` is the number at the end of the pull request title and `BASEBRANCH` the base branch of the pull request.-- The [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) tool can be used to review a pull request content in a single command. `PRNUMBER` should be replaced by the number at the end of the pull request title. You can also provide the full github pull request url.+- The [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) tool can be used to review a pull request content in a single command.···-New packages are a common type of pull requests. These pull requests consists in adding a new nix-expression for a package.···- Ensure that the meta fields [fits the guidelines](#meta-attributes) and contain the correct information:-- Maintainers must be set. This can be the package submitter or a community member that accepts taking up maintainership of the package.+This can be the package submitter or a community member that accepts taking up maintainership of the package.- Ensure any special packaging choices and required context are documented in i.e. the name of a patch or in a comment.