From b4532efe93882ae2e3fc579929a42a5a56544146 Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Sun, 29 Jun 2025 18:33:08 +0200 Subject: [PATCH] **/README.md: one sentence per line As documented in doc/README.md. --- CONTRIBUTING.md | 124 ++++++----- README.md | 56 ++--- doc/README.md | 31 ++- lib/deprecated/README.md | 3 +- lib/fileset/README.md | 6 +- lib/path/README.md | 59 +++-- maintainers/README.md | 207 +++++++----------- maintainers/scripts/README.md | 19 +- maintainers/scripts/auto-rebase/README.md | 3 +- maintainers/scripts/bootstrap-files/README.md | 66 ++---- nixos/README.md | 15 +- nixos/doc/manual/README.md | 3 +- pkgs/README.md | 162 ++++++++++---- 13 files changed, 392 insertions(+), 362 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b3e9b4bdb1f..8694c7fe96d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,7 +125,8 @@ This section describes in some detail how changes can be made and proposed with ### Pull request template [pr-template]: #pull-request-template -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. When a PR is created, it will be pre-populated with some checkboxes detailed below: @@ -149,15 +150,22 @@ Please enable sandboxing **before** building the package by adding the following #### Built on platform(s) -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. +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. #### 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. +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). #### Tested compilation of all pkgs that depend on this change using `nixpkgs-review` -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. Review changes from pull request number 12345: @@ -185,23 +193,23 @@ nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD" #### Tested execution of all binary files (usually in `./result/bin/`) -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. #### Meets Nixpkgs contribution standards -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. +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. ### Rebasing between branches (i.e. from master to staging) [rebase]: #rebasing-between-branches-ie-from-master-to-staging -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. +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. +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. ```console @@ -211,14 +219,10 @@ git rebase --onto upstream/staging... upstream/master git push origin feature --force-with-lease ``` -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`). +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. +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. ```console # Rebase onto target branch @@ -272,13 +276,19 @@ To manually create a backport pull request, follow [the standard pull request pr > [!Warning] > 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 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. +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. -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. When doing a review: - Aim to drive the proposal to a timely conclusion. @@ -298,34 +308,36 @@ If the related change is essential for the contribution at hand, make clear why 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. +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. +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. Container system, boot system and library changes are some examples of the pull requests fitting this category. ## How to merge pull requests yourself [pr-merge]: #how-to-merge-pull-requests -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`. +The bot will verify if the following conditions are met, refusing to merge otherwise: - the PR author should be @r-ryantm or a Nixpkgs committer; - the commenter that issued the command should be among the package maintainers; - the package should reside in `pkgs/by-name`. -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. +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. #### Admonitions @@ -326,8 +333,11 @@ Otherwise, just describe the single argument or start the arguments' definition Checklist: - Start with a synopsis, to show the order of positional arguments. -- 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. +- 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:`_ if it's easily described as a value. - _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value. - Nix types aren't in code spans, because they are not code @@ -404,7 +414,8 @@ This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-re #### Typographic replacements -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). +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). ## Getting help diff --git a/lib/deprecated/README.md b/lib/deprecated/README.md index afeb34d449f5..9591afad0d3f 100644 --- a/lib/deprecated/README.md +++ b/lib/deprecated/README.md @@ -4,8 +4,7 @@ Do not add any new functions to this directory. This directory contains the `lib.misc` sublibrary, which - as a location - is deprecated. -Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided, -while some functions *may still be needed*. +Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided, while some functions *may still be needed*. This directory does not play a role in the deprecation process for library functions. They should be deprecated in place, by putting a `lib.warn` or `lib.warnIf` call around the function. diff --git a/lib/fileset/README.md b/lib/fileset/README.md index 646de07e669a..80e7146992a8 100644 --- a/lib/fileset/README.md +++ b/lib/fileset/README.md @@ -166,7 +166,8 @@ Meanwhile `intersection ./foo ./bar` returns the empty file set without a base p Arguments: - Alternative: Use the common prefix of all base paths as the resulting base path - - (-) 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. + It should be as long as possible. 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 @@ -263,5 +264,6 @@ Coercing paths that don't exist to file sets always gives an error. - (+) This is dangerous, because you wouldn't be protected against typos anymore. 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. This could be fixed, but would require significant changes to the internal representation that are not worth the effort and the risk of introducing implicit behavior. diff --git a/lib/path/README.md b/lib/path/README.md index 89eec18b1130..2ebe85637e22 100644 --- a/lib/path/README.md +++ b/lib/path/README.md @@ -2,7 +2,8 @@ This document explains why the `lib.path` library is designed the way it is. -The purpose of this library is to process [filesystem paths]. It does not read files from the filesystem. +The purpose of this library is to process [filesystem paths]. +It does not read files from the filesystem. It exists to support the native Nix [path value type] with extra functionality. [filesystem paths]: https://en.m.wikipedia.org/wiki/Path_(computing) @@ -11,11 +12,15 @@ It exists to support the native Nix [path value type] with extra functionality. As an extension of the path value type, it inherits the same intended use cases and limitations: - Only use paths to access files at evaluation time, such as the local project source. - Paths cannot point to derivations, so they are unfit to represent dependencies. -- 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. Overall, this library works with two types of paths: -- 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. +- 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. A subpath refers to a specific file or directory within an absolute base directory. It is a stricter form of a relative path, notably [without support for `..` components][parents] since those could escape the base directory. @@ -24,7 +29,8 @@ Overall, this library works with two types of paths: 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. +Contrary to these library components, `lib.path` does not read any paths from the filesystem. This library makes only these assumptions about paths and no others: - `dirOf path` returns the path to the parent directory of `path`, unless `path` is the filesystem root, in which case `path` is returned. @@ -53,9 +59,15 @@ Decision: Returned subpaths should always have a leading `./`.
Arguments -- (+) 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. + 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. - (+) Prepending with `./` makes the subpaths always valid as relative Nix path expressions. -- (+) 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`. + This is not a problem with `./--version`. + This effectively then means that paths don't overlap with GNU-style command line options. - (-) `./` is not required to resolve relative paths, resolution always has an implicit `./` as prefix. - (-) It's less noisy without the `./`, e.g. in error messages. - (+) But similarly, it could be confusing whether something was even a path. @@ -63,7 +75,8 @@ Decision: Returned subpaths should always have a leading `./`. - (+) Makes it more uniform with absolute paths (those always start with `/`). - (-) That is not relevant for practical purposes. - (+) `find` also outputs results with `./`. - - (-) But only if you give it an argument of `.`. If you give it the argument `some-directory`, it won't prefix that. + - (-) But only if you give it an argument of `.`. + If you give it the argument `some-directory`, it won't prefix that. - (-) `realpath --relative-to` doesn't prefix relative paths with `./`. - (+) There is no need to return the same result as `realpath`. @@ -84,7 +97,8 @@ Decision: It should be `./.`. - (+) `./` would be inconsistent with [the decision to not persist trailing slashes][trailing-slashes]. - (-) `.` is how `realpath` normalises paths. - (+) `.` 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. +- (+) `.` 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. - (-) `./.` is rather long. - (-) We don't require users to type this though, as it's only output by the library. As inputs all three variants are supported for subpaths (and we can't do anything about absolute paths) @@ -102,14 +116,16 @@ Observing: Subpaths such as `foo/bar` can be represented in various ways: - list with all the components: `[ "foo" "bar" ]` - attribute set: `{ type = "relative-path"; components = [ "foo" "bar" ]; }` -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. +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. Decision: Paths are represented as strings.
Arguments -- (+) It's simpler for the users of the library. One doesn't have to convert a path a string before it can be used. +- (+) 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 `[ ]`. @@ -125,18 +141,22 @@ Observing: Relative paths can have `..` components, which refer to the parent di Considering: Paths should be as safe and unambiguous as possible. -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. +Hence, string paths are called subpaths, rather than relative paths.
Arguments - (+) 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. + It is simpler, and not using symlinks at all is safer. - (+) Mixing both models can lead to surprises. - (+) We can't resolve symlinks without filesystem access. - (+) Nix also doesn't support reading symlinks at evaluation time. - - (-) 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. + - (-) 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. - (-) 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. - (-) `..` are a part of paths, a path library should therefore support it. - (+) 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. @@ -163,7 +183,8 @@ Decision: All functions remove trailing slashes in their results.
Arguments -- (+) 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. - Comparison to other frameworks to figure out the least surprising behavior: - (+) 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). @@ -192,7 +213,8 @@ Decision: All functions remove trailing slashes in their results. Observing: Functions could return subpaths or lists of path component strings. -Considering: Subpaths are used as inputs for some functions. Using them for outputs, too, makes the library more consistent and composable. +Considering: Subpaths are used as inputs for some functions. +Using them for outputs, too, makes the library more consistent and composable. Decision: Subpaths should be preferred over list of path component strings. @@ -203,7 +225,8 @@ Decision: Subpaths should be preferred over list of path component strings. - (-) 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 - (+) If necessary, we can still make it faster by adding builtins to Nix - (+) 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. +- (+) 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.
diff --git a/maintainers/README.md b/maintainers/README.md index ee1762a34536..70687604b611 100644 --- a/maintainers/README.md +++ b/maintainers/README.md @@ -1,71 +1,56 @@ # Nixpkgs Maintainers -Unlike other packaging ecosystems, the maintainer doesn't have exclusive -control over the packages and modules they maintain. This more fluid approach -is one reason why we scale to so many packages. +Unlike other packaging ecosystems, the maintainer doesn't have exclusive control over the packages and modules they maintain. +This more fluid approach is one reason why we scale to so many packages. ## Definition and role of the maintainer -The main responsibility of a maintainer is to keep the packages they maintain -in a functioning state, and keep up with updates. In order to do that, they -are empowered to make decisions over the packages they maintain. +The main responsibility of a maintainer is to keep the packages they maintain in a functioning state, and keep up with updates. +In order to do that, they are empowered to make decisions over the packages they maintain. -That being said, the maintainer is not alone proposing changes to the -packages. Anybody (both bots and humans) can send PRs to bump or tweak the -package. +That being said, the maintainer is not alone proposing changes to the packages. +Anybody (both bots and humans) can send PRs to bump or tweak the package. -We also allow other non-maintainer committers to merge changes to the package, -provided enough time and priority has been given to the maintainer. +We also allow other non-maintainer committers to merge changes to the package, provided enough time and priority has been given to the maintainer. -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). This should leave enough time -for the maintainers to provide feedback. +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). +This should leave enough time for the maintainers to provide feedback. -For critical packages, this convention needs to be negotiated with the -maintainer. A critical package is one that causes mass-rebuild, or where an -author is listed in the [`OWNERS`](../ci/OWNERS) file. +For critical packages, this convention needs to be negotiated with the maintainer. +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 -heuristics in order to get the fixes in as fast as possible. +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 case of conflict, the maintainer takes priority and is allowed to revert -the changes. This can happen for example if the maintainer was on holiday. +In case of conflict, the maintainer takes priority and is allowed to revert the changes. +This can happen for example if the maintainer was on holiday. ### How to become a maintainer -We encourage people who care about a package to assign themselves as a -maintainer. Commit access to the Nixpkgs repository is not required for that. +We encourage people who care about a package to assign themselves as a maintainer. +Commit access to the Nixpkgs repository is not required for that. -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. +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 +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 `maintainer-list.nix` in a separate commit titled `maintainers: add `. ### How to lose maintainer status -Maintainers who have become inactive on a given package can be removed. This -helps us keep an accurate view of the state of maintenance in Nixpkgs. +Maintainers who have become inactive on a given package can be removed. +This helps us keep an accurate view of the state of maintenance in Nixpkgs. -The inactivity measure is currently not strictly enforced. We would typically -look at it if we notice that the author hasn't reacted to package-related -notifications for more than 3 months. +The inactivity measure is currently not strictly enforced. +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. +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. The maintainer is welcome to come back at any time. ## Tools for maintainers -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. +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. @@ -77,33 +62,26 @@ Should it expire, please ask for a re-invite in the [GitHub org owners help desk [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 -you if nixpkgs-update/@r-ryantm fails to update any of the packages you've subscribed to. +[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. +Example: [repology.org/maintainer/pbsds](https://repology.org/maintainer/pbsds%40hotmail.com). -[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. +[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. ## Reviewing contributions ### Individual maintainer list -When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the following -checks should be performed: +When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the following checks should be performed: -- If the user has specified a GPG key, verify that the commit is - signed by their key. +- If the user has specified a GPG key, verify that the commit is signed by their key. - First, validate that the commit adding the maintainer is signed by - the key the maintainer listed. Check out the pull request and - compare its signing key with the listed key in the commit. + First, validate that the commit adding the maintainer is signed by the key the maintainer listed. + Check out the pull request and compare its signing key with the listed key in the commit. - 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. + 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. Given a maintainer entry like this: @@ -138,19 +116,14 @@ checks should be performed: maintainers: adding example - and validate that there is a `Good signature` and the printed key - matches the user's submitted key. + 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. + 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. +- If the user has specified a `github` account name, ensure they have also specified a `githubId` and verify the two match. - Maintainer entries that include a `github` field must also include - their `githubId`. People can and do change their GitHub name - frequently, and the ID is used as the official and stable identity - of the maintainer. + Maintainer entries that include a `github` field must also include their `githubId`. + People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer. Given a maintainer entry like this: @@ -165,92 +138,68 @@ checks should be performed: } ``` - First, make sure that the listed GitHub handle matches the author of - the commit. + First, make sure that the listed GitHub handle matches the author of the commit. - Then, visit the URL `https://api.github.com/users/ghost` and - validate that the `id` field matches the provided `githubId`. + Then, visit the URL `https://api.github.com/users/ghost` and validate that the `id` field matches the provided `githubId`. ### Maintainer teams -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. +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. Use taste and personal judgement when deciding if a team is warranted. Teams are allowed to define their own rules about membership. -For example, some teams will represent a business or other group which -wants to carefully track its members. Other teams may be very open about -who can join, and allow anybody to participate. +For example, some teams will represent a business or other group which wants to carefully track its members. +Other teams may be very open about who can join, and allow anybody to participate. -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. +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. -In any case, request reviews from the existing team members. 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. +In any case, request reviews from the existing team members. +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. +*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. # Maintainer scripts -Various utility scripts, which are mainly useful for nixpkgs maintainers, -are available under `./scripts/`. See its [README](./scripts/README.md) -for further information. +Various utility scripts, which are mainly useful for nixpkgs maintainers, are available under `./scripts/`. +See its [README](./scripts/README.md) for further information. # nixpkgs-merge-bot -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. # Guidelines for Committers -When merging pull requests, care must be taken to reduce impact to the `master` -branch. 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. +When merging pull requests, care must be taken to reduce impact to the `master` branch. +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. +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. ## Breaking changes -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 restrictions also intend to -decrease the likelihood of a delayed NixOS release. The feature freeze period -is documented in the announcement of each release schedule. +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 restrictions also intend to decrease the likelihood of a delayed NixOS release. +The feature freeze period is documented in the announcement of each release schedule. -> These are some example changes and if they are considered a breaking change -> during a freeze period: +> These are some example changes and if they are considered a breaking change during a freeze period: > -> - `foo: 1.2.3 -> 1.2.4` - 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. -> - `unmaintained-software: drop` - If this PR removes a leaf package or the -> removal doesn't otherwise break other packages, it can be merged. -> - `cool-tool: rename from fancy-tool` - 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. -> - `libpopular: 4.3.2 -> 5.0.0` - 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. -> - `nixos/transmission: refactor` - 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. +> - `foo: 1.2.3 -> 1.2.4`: +> 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. +> - `unmaintained-software: drop`: +> If this PR removes a leaf package or the removal doesn't otherwise break other packages, it can be merged. +> - `cool-tool: rename from fancy-tool`: +> 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. +> - `libpopular: 4.3.2 -> 5.0.0`: +> 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. +> - `nixos/transmission: refactor`: +> 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. diff --git a/maintainers/scripts/README.md b/maintainers/scripts/README.md index a80942bb7343..81b2873788a4 100644 --- a/maintainers/scripts/README.md +++ b/maintainers/scripts/README.md @@ -1,21 +1,17 @@ # Maintainer scripts -This folder contains various executable scripts for nixpkgs maintainers, -and supporting data or nixlang files as needed. +This folder contains various executable scripts for nixpkgs maintainers, and supporting data or nixlang files as needed. These scripts generally aren't a stable interface and may changed or be removed. What follows is a (very incomplete) overview of available scripts. - ## Metadata ### `get-maintainer.sh` -`get-maintainer.sh [selector] value` returns a JSON object describing -a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`. +`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 +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 robustly than text search through `maintainer-list.nix`. ``` @@ -52,16 +48,14 @@ robustly than text search through `maintainer-list.nix`. The maintainer is designated by a `selector` which must be one of: - `handle` (default): the maintainer's attribute name in `lib.maintainers`; - `email`, `name`, `github`, `githubId`, `matrix`, `name`: - attributes of the maintainer's object, matched exactly; - see [`maintainer-list.nix`] for the fields' definition. + attributes of the maintainer's object, matched exactly; see [`maintainer-list.nix`] for the fields' definition. [`maintainer-list.nix`]: ../maintainer-list.nix ### `get-maintainer-pings-between.sh` Gets which maintainers would be pinged between two Nixpkgs revisions. -Outputs a JSON object on stdout mapping GitHub usernames to the attributes -that they would be getting pinged for. +Outputs a JSON object on stdout mapping GitHub usernames to the attributes that they would be getting pinged for. Example: @@ -73,8 +67,7 @@ maintainers/scripts/get-maintainer-pings-between.sh HEAD^ HEAD ### `sha-to-sri.py` -`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}"`. +`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}"`. `path` must point to either a nix file, or a directory which will be automatically traversed. diff --git a/maintainers/scripts/auto-rebase/README.md b/maintainers/scripts/auto-rebase/README.md index 926aa6c99d9f..e9c61da05c93 100644 --- a/maintainers/scripts/auto-rebase/README.md +++ b/maintainers/scripts/auto-rebase/README.md @@ -1,7 +1,6 @@ # Auto rebase script -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). See the header comment of that file to understand how to mark commits. This is convenient for resolving merge conflicts for pull requests after e.g. treewide reformats. diff --git a/maintainers/scripts/bootstrap-files/README.md b/maintainers/scripts/bootstrap-files/README.md index 4bd7d8c58937..af8181c2c3ac 100644 --- a/maintainers/scripts/bootstrap-files/README.md +++ b/maintainers/scripts/bootstrap-files/README.md @@ -1,30 +1,23 @@ # Bootstrap files -Currently `nixpkgs` builds most of it's packages using bootstrap seed -binaries (without the reliance on external inputs): +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`. -- initial binaries needed to unpack `bootstrap-tools.*`. 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-tools`: an archive with the compiler toolchain and other helper tools enough to build the rest of the `nixpkgs`. +- initial binaries needed to unpack `bootstrap-tools.*`. + 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. These binaries can be executed directly from the store. These are called "bootstrap files". -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. +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. The uploads to `tarballs.nixos.org` are done by `@lovesegfault` today. -This document describes the procedure of updating bootstrap files in -`nixpkgs`. +This document describes the procedure of updating bootstrap files in `nixpkgs`. ## How to request the bootstrap seed update -To get the tarballs updated let's use an example `i686-unknown-linux-gnu` -target: +To get the tarballs updated let's use an example `i686-unknown-linux-gnu` target: 1. Create a local update: @@ -32,61 +25,51 @@ target: $ maintainers/scripts/bootstrap-files/refresh-tarballs.bash --commit --targets=i686-unknown-linux-gnu ``` -2. Test the update locally. I'll build local `hello` derivation with - the result: +2. Test the update locally. I'll build local `hello` derivation with the result: ``` $ nix-build -A hello --argstr system i686-linux ``` To validate cross-targets `binfmt` `NixOS` helper can be useful. - For `riscv64-unknown-linux-gnu` the `/etc/nixos/configuration.nix` - entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`. + 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. +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. ## How to add bootstrap files for a new target -The procedure to add a new target is very similar to the update -procedure. The only difference is that you need to set up a new job to -build the `bootstrapFiles`. To do that you will need the following: +The procedure to add a new target is very similar to the update procedure. +The only difference is that you need to set up a new job to build the `bootstrapFiles`. +To do that you will need the following: 1. Add your new target to `lib/systems/examples.nix` - This will populate `pkgsCross.$target` attribute set. If you are - dealing with `bootstrapFiles` upload you probably already have it. + This will populate `pkgsCross.$target` attribute set. + If you are dealing with `bootstrapFiles` upload you probably already have it. -2. Add your new target to - `pkgs/stdenv/linux/make-bootstrap-tools-cross.nix`. This will add a - new hydra job to `nixpkgs:cross-trunk` jobset. +2. Add your new target to `pkgs/stdenv/linux/make-bootstrap-tools-cross.nix`. + This will add a new hydra job to `nixpkgs:cross-trunk` jobset. 3. Wait for a hydra to build your bootstrap tarballs. -4. Add your new target to - `maintainers/scripts/bootstrap-files/refresh-tarballs.bash` around - `CROSS_TARGETS=()`. +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. +5. Add your new target to `pkgs/stdenv/linux/default.nix` and follow standard bootstrap seed update procedure above. ## Bootstrap files job definitions There are two types of bootstrap files: -- natively built `stdenvBootstrapTools.build` hydra jobs in - [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs) - jobset. Incomplete list of examples is: +- natively built `stdenvBootstrapTools.build` hydra jobs in [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs) jobset. + Incomplete list of examples is: * `aarch64-unknown-linux-musl.nix` * `i686-unknown-linux-gnu.nix` These are Tier 1 hydra platforms. -- cross-built by `bootstrapTools.build` hydra jobs in - [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs) - jobset. Incomplete list of examples is: +- cross-built by `bootstrapTools.build` hydra jobs in [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs) jobset. + Incomplete list of examples is: * `mips64el-unknown-linux-gnuabi64.nix` * `mips64el-unknown-linux-gnuabin32.nix` @@ -96,6 +79,5 @@ There are two types of bootstrap files: These are usually Tier 2 and lower targets. -The `.build` job contains `/on-server/` subdirectory with binaries to -be uploaded to `tarballs.nixos.org`. +The `.build` job contains `/on-server/` subdirectory with binaries to be uploaded to `tarballs.nixos.org`. The files are uploaded to `tarballs.nixos.org` by writers to `S3` store. diff --git a/nixos/README.md b/nixos/README.md index 8e6d44410ef3..65bcafabe913 100644 --- a/nixos/README.md +++ b/nixos/README.md @@ -1,12 +1,12 @@ # NixOS -NixOS is a Linux distribution based on the purely functional package -management system Nix. More information can be found at -https://nixos.org/nixos and in the manual in doc/manual. +NixOS is a Linux distribution based on the purely functional package management system Nix. +More information can be found at https://nixos.org/nixos and in the manual in doc/manual. ## Testing changes -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= --fast`. +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= --fast`. ## Commit conventions @@ -31,11 +31,14 @@ You can add new module to your NixOS configuration file (usually it’s `/etc/ni ## Reviewing contributions -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. +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. ### Module updates -Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options. +Module updates are submissions changing modules in some ways. +These often contains changes to the options or introduce new options. Reviewing process: diff --git a/nixos/doc/manual/README.md b/nixos/doc/manual/README.md index bc649761df69..a7e15353eec5 100644 --- a/nixos/doc/manual/README.md +++ b/nixos/doc/manual/README.md @@ -1,3 +1,4 @@ -[Moved to ./contributing-to-this-manual.chapter.md](./contributing-to-this-manual.chapter.md). Link: +[Moved to ./contributing-to-this-manual.chapter.md](./contributing-to-this-manual.chapter.md). +Link: https://nixos.org/manual/nixos/unstable/#chap-contributing diff --git a/pkgs/README.md b/pkgs/README.md index ee98b2e7de35..83d264d95085 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -24,26 +24,40 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat ## Quick Start to Adding a Package -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. Before adding a new package, please consider the following questions: -* 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. +* 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. * In case you are not able to maintain the package you wrote, you can seek someone to fill that role, effectively adopting the package. If any of these questions' answer is no, then you should probably not add 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. +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. * Any package that immediately would need to be tagged with `meta.knownVulnerabilities` is unlikely to be fit for nixpkgs. * Any package depending on a known-vulnerable library should be considered carefully. -* 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. + 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. * Services which typically work on web traffic are working on untrusted input. * 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. @@ -54,7 +68,8 @@ Special care has to be taken with security-critical software components. Because * being responsive to security concerns, providing fixes or workarounds * transparent public disclosure of security issues when they are found or fixed * 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. +* Source-available software should be built from source where possible. + Binary blobs risk supply chain attacks and vendored outdated libraries. This section describes a general framework of understanding and exceptions might apply. @@ -62,7 +77,8 @@ Luckily it's pretty easy to maintain your own package set with Nix, which can th --- -Now that this is out of the way. To add a package to Nixpkgs: +Now that this is out of the way. +To add a package to Nixpkgs: 1. Checkout the Nixpkgs source tree: @@ -79,7 +95,8 @@ Now that this is out of the way. To add a package to Nixpkgs: For more detailed information, see [here](./by-name/README.md). -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. ```ShellSession $ emacs pkgs/by-name/so/some-package/package.nix @@ -91,23 +108,35 @@ Now that this is out of the way. To add a package to Nixpkgs: 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). Here are some good ones: - - 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 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 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). + Also done by the generic builder, but has a dependency on `m4`. - - 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). + Has an optional dependency on `gspell`, which is only built if `spellCheck` is `true`. - - 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). + A reusable build function for Firefox, Thunderbird and Librewolf. - - 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). + Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc. - - 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). + 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. Some notes: @@ -125,7 +154,9 @@ Now that this is out of the way. To add a package to Nixpkgs: $ nix-build -A some-package ``` - 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. + 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. 6. If you want to install the package into your profile (optional), do @@ -351,19 +382,22 @@ A (typically large) program with a distinct user interface, primarily used inter # Conventions -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). +Only _emphasized_ words are to be interpreted in this way. ## Package naming In Nixpkgs, there are generally three different names associated with a package: -- The `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`. +- 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. - The filename for (the directory containing) the Nix expression. -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`. +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`. Follow these guidelines: @@ -379,7 +413,8 @@ Follow these guidelines: - It _must_ be a valid identifier in 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. + Otherwise the attribute name _should not_ be prefixed with an underline. Example: The corresponding attribute name for `0ad` should be `_0ad`. @@ -404,11 +439,13 @@ Follow these guidelines: These are the guidelines the `version` attribute of a package: -- 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). +- 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). Example: `"0.3.1rc2"` or `"0-unstable-1970-01-01"` -- 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. + 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"`. @@ -416,9 +453,14 @@ These are the guidelines the `version` attribute of a package: 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 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 @@ -437,7 +479,8 @@ The `meta` attribute set should always be placed last in the derivativion and an * 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 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`. @@ -517,11 +560,17 @@ Sometimes, changes are needed to the source to allow building a derivation in ni When using the `patches` parameter to `mkDerivation`, make sure the patch name clearly describes the reason for the patch, or add a comment. > [!Note] -> 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). +> 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). > > See [Versioning](#versioning) for details on package versioning. -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"_. +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"_. ### Fetching patches @@ -544,9 +593,11 @@ In the interest of keeping our maintenance burden and the size of Nixpkgs to a m > 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. +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. ### Vendoring patches @@ -601,7 +652,8 @@ We use jbidwatcher as an example for a discontinued project here. 1. Create a new branch for your change, e.g. `git checkout -b jbidwatcher` 1. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher` 1. Remove the package from the list of all packages (`pkgs/top-level/all-packages.nix`). -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`. + Package sets typically do not have aliases, so we can't add them there.) For example in this case: @@ -613,8 +665,11 @@ We use jbidwatcher as an example for a discontinued project here. 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. +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. ```ShellSession $ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix @@ -632,7 +687,8 @@ We use jbidwatcher as an example for a discontinued project here. ``` 1. Push changes to your GitHub fork with `git push` -1. Create a pull request against Nixpkgs. Mention the package maintainer. +1. Create a pull request against Nixpkgs. + Mention the package maintainer. 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) @@ -649,8 +705,11 @@ Tests are important to ensure quality and make reviews and automatic updates eas The following types of tests exists: -* [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. + 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. * 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). @@ -886,7 +945,8 @@ Each update script will be passed the following environment variables: - [`UPDATE_NIX_NAME`] – content of the `name` attribute of the updated package - [`UPDATE_NIX_PNAME`] – content of the `pname` attribute of the updated package - [`UPDATE_NIX_OLD_VERSION`] – content of the `version` attribute of the updated package -- [`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). + Example: `pantheon.elementary-terminal` > [!Note] > An update script will be usually run from the root of the Nixpkgs repository, but you should not rely on that. @@ -937,7 +997,8 @@ If you need to customize commit message, you can have the update script implemen ### Package updates -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. +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. It can happen that non-trivial updates include patches or more complex changes. @@ -949,7 +1010,8 @@ Reviewing process: - 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. + - 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. - Verify any change of upstream. - If switching from e.g. PyPi to GitHub, verify that the repo is the official one. - If switching to a fork, check with external sources like other package repositories for community consensus. @@ -972,7 +1034,9 @@ Reviewing process: - The first command fetches the nixos-unstable branch. - 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 third command rebases the pull request changes to the nixos-unstable branch. - - 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. + `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. ```ShellSession $ nix-shell -p nixpkgs-review --run "nixpkgs-review pr PRNUMBER" @@ -1001,7 +1065,8 @@ Sample template for a package update review is provided below. ### New packages -New packages are a common type of pull requests. These pull requests consists in adding a new nix-expression for a package. +New packages are a common type of pull requests. +These pull requests consists in adding a new nix-expression for a package. Review process: @@ -1013,7 +1078,8 @@ Review process: - Ensure that the meta fields [fits the guidelines](#meta-attributes) and contain the correct information: - License must match the upstream license. - Platforms should be set (or the package will not get binary substitutes). - - Maintainers must be set. This can be the package submitter or a community member that accepts taking up maintainership of the package. + - Maintainers must be set. + This can be the package submitter or a community member that accepts taking up maintainership of the package. - The `meta.mainProgram` must be set if a main executable exists. - Ensure any special packaging choices and required context are documented in i.e. the name of a patch or in a comment. - If a special version of a package is pinned, document why, so others know if/when it can be unpinned.