**/README.md: one sentence per line

As documented in doc/README.md.
2025-07-13 21:50:33 +03:00 · 2025-06-29 18:33:08 +02:00 · 2025-06-29 18:33:08 +02:00 · b4532efe93
commit b4532efe93
parent 2369d96548
13 changed files with 392 additions and 362 deletions
--- 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
+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.
 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`,
+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`.
-is based on `master`, and we rebase it onto the merge base between
+The example uses `upstream` as the remote for `NixOS/nixpkgs.git` while `origin` is the remote you are pushing to.
 `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
+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`).
 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
+Then change the base branch in the GitHub PR using the *Edit* button in the upper right corner, and switch from `master` to `staging`.
-right corner, and switch from `master` to `staging`. *After* the PR has been
+*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.
 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
+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).
-change (a typo, capitalisation change, etc.) and the author allowed the members
+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.
 to modify the PR, consider applying it yourself (or commit the existing review
 suggestion). You should pay extra attention to make sure the addition doesn't go
 against the idea of the original PR and would not be opposed by the author.
 <!--
 The following paragraphs about how to deal with unactive contributors is just a proposition and should be modified to what the community agrees to be the right policy.
@ -362,8 +374,7 @@ It is coordinated in the [Staging room](https://matrix.to/#/#staging:nixos.org)
 It works by directing commits that cause [mass rebuilds][mass-rebuild] to a separate `staging` branch that isn't directly built by Hydra.
 Regularly, the `staging` branch is _manually_ merged into a `staging-next` branch to be built by Hydra using the [`nixpkgs:staging-next` jobset](https://hydra.nixos.org/jobset/nixpkgs/staging-next).
-The `staging-next` branch should then only receive changes that fix Hydra builds;
+The `staging-next` branch should then only receive changes that fix Hydra builds; **for anything else, ask the [Staging room](https://matrix.to/#/#staging:nixos.org) first**.
 **for anything else, ask the [Staging room](https://matrix.to/#/#staging:nixos.org) first**.
 Once it is verified that there are no major regressions, it is merged into `master` using [a pull request](https://github.com/NixOS/nixpkgs/pulls?q=head%3Astaging-next).
 This is done manually in order to ensure it's a good use of Hydra's computing resources.
 By keeping the `staging-next` branch separate from `staging`, this batching does not block developers from merging changes into `staging`.
@ -495,7 +506,8 @@ To get a sense for what changes are considered mass rebuilds, see [previously me
 - Check for unnecessary whitespace with `git diff --check` before committing.
- If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`.
+- If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case.
  Use `git rebase -i`.
  See [Squashing Commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) for additional information.
 - For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message).
@ -505,7 +517,8 @@ To get a sense for what changes are considered mass rebuilds, see [previously me
  Add the commit before those making changes to the package or module.
  See [Nixpkgs Maintainers](./maintainers/README.md) for details.
- Make sure you read about any commit conventions specific to the area you're touching. See:
+- Make sure you read about any commit conventions specific to the area you're touching.
  See:
  - [Commit conventions](./pkgs/README.md#commit-conventions) for changes to `pkgs`.
  - [Commit conventions](./lib/README.md#commit-conventions) for changes to `lib`.
  - [Commit conventions](./nixos/README.md#commit-conventions) for changes to `nixos`.
@ -514,9 +527,11 @@ To get a sense for what changes are considered mass rebuilds, see [previously me
 ### Writing good commit messages
 [writing-good-commit-messages]: #writing-good-commit-messages
-In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.
+In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made.
 While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.
-Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.
+Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog.
 Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.
 Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.
@ -529,12 +544,12 @@ If you removed packages or made some major NixOS changes, write about it in the
 ### File naming and organisation
-Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.
+Names of files and directories should be in lowercase, with dashes between words — not in camel case.
 For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.
 ### Formatting
-CI [enforces](./.github/workflows/check-format.yml) all Nix files to be
+CI [enforces](./.github/workflows/check-format.yml) all Nix files to be formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).
 formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).
 You can ensure this locally using either of these commands:
 ```
@ -543,20 +558,19 @@ nix develop --command treefmt
 nix fmt
 ```
-If you're starting your editor in `nix-shell` or `nix develop`,
+If you're starting your editor in `nix-shell` or `nix develop`, you can also set it up to automatically format the file with `treefmt` on save.
 you can also set it up to automatically format the file with `treefmt` on save.
-If you have any problems with formatting, please ping the
+If you have any problems with formatting, please ping the [formatting team](https://nixos.org/community/teams/formatting/) via [@NixOS/nix-formatting](https://github.com/orgs/NixOS/teams/nix-formatting).
 [formatting team](https://nixos.org/community/teams/formatting/) via
 [@NixOS/nix-formatting](https://github.com/orgs/NixOS/teams/nix-formatting).
 ### Syntax
 - Set up [editorconfig](https://editorconfig.org/) for your editor, such that [the settings](./.editorconfig) are automatically applied.
- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).
+- Use `lowerCamelCase` for variable names, not `UpperCamelCase`.
  Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).
- Functions should list their expected arguments as precisely as possible. That is, write
+- Functions should list their expected arguments as precisely as possible.
  That is, write
  ```nix
  { stdenv, fetchurl, perl }: <...>
@ -594,7 +608,8 @@ If you have any problems with formatting, please ping the
  })
  ```
- Unnecessary string conversions should be avoided. Do
+- Unnecessary string conversions should be avoided.
  Do
  ```nix
  {
@ -707,8 +722,10 @@ Ask them nicely whether they still intend to review your PR and find yourself an
 - Improve skimmability: use a simple descriptive PR title (details go in commit titles) outlining _what_ is done and _why_.
 - Improve discoverability: apply all relevant labels, tick all relevant PR body checkboxes.
- Wait. Reviewers frequently browse open PRs and may happen to run across yours and take a look.
+- Wait.
- Get non-committers to review/approve. Many committers filter open PRs for low-hanging fruit that are already been reviewed.
+  Reviewers frequently browse open PRs and may happen to run across yours and take a look.
 - Get non-committers to review/approve.
  Many committers filter open PRs for low-hanging fruit that are already been reviewed.
 - [@-mention](https://github.blog/news-insights/mention-somebody-they-re-notified/) someone and ask them nicely
 - Post in one of the channels made for this purpose if there has been no activity for at least one week
  - The current "PRs ready for review" or "PRs already reviewed" threads in the [NixOS Discourse](https://discourse.nixos.org/c/dev/14) (of course choose the one that applies to your situation)
@ -723,7 +740,8 @@ If it is indeed caused by your change, obviously try to fix it.
 Don't be afraid of asking for advice if you're uncertain how to do that, others have likely fixed such issues dozens of times and can help you out.
 Your PR is unlikely to be merged if it has a known issue and it is the purpose of CI to alert you aswell as reviewers to these issues.
-ofBorg builds can often get stuck, particularly in PRs targeting `staging` and in builders for the Darwin platform. Reviewers will know how to handle them or when to ignore them.
+ofBorg builds can often get stuck, particularly in PRs targeting `staging` and in builders for the Darwin platform.
 Reviewers will know how to handle them or when to ignore them.
 Don't worry about it.
 If there is a build failure however and it happened due to a package related to your change, you need to investigate it of course.
 If ofBorg reveals the build to be broken on some platform and you don't have access to that platform, you should set your package's `meta.broken` accordingly.
--- a/README.md
+++ b/README.md
@ -13,10 +13,8 @@
  <a href="https://opencollective.com/nixos"><img src="https://opencollective.com/nixos/tiers/supporter/badge.svg?label=supporters&color=brightgreen" alt="Open Collective supporters" /></a>
 </p>
-[Nixpkgs](https://github.com/nixos/nixpkgs) is a collection of over
+[Nixpkgs](https://github.com/nixos/nixpkgs) is a collection of over 120,000 software packages that can be installed with the [Nix](https://nixos.org/nix/) package manager.
-120,000 software packages that can be installed with the
+It also implements [NixOS](https://nixos.org/nixos/), a purely-functional Linux distribution.
 [Nix](https://nixos.org/nix/) package manager. It also implements
 [NixOS](https://nixos.org/nixos/), a purely-functional Linux distribution.
 # Manuals
@ -34,9 +32,8 @@
 # Other Project Repositories
-The sources of all official Nix-related projects are in the [NixOS
+The sources of all official Nix-related projects are in the [NixOS organization on GitHub](https://github.com/NixOS/).
-organization on GitHub](https://github.com/NixOS/). Here are some of
+Here are some of the main ones:
 the main ones:
 * [Nix](https://github.com/NixOS/nix) - the purely functional package manager
 * [NixOps](https://github.com/NixOS/nixops) - the tool to remotely deploy NixOS machines
@ -48,44 +45,33 @@ the main ones:
 # Continuous Integration and Distribution
-Nixpkgs and NixOS are built and tested by our continuous integration
+Nixpkgs and NixOS are built and tested by our continuous integration system, [Hydra](https://hydra.nixos.org/).
 system, [Hydra](https://hydra.nixos.org/).
 * [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
 * [Continuous package builds for the NixOS 25.05 release](https://hydra.nixos.org/jobset/nixos/release-25.05)
 * [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
 * [Tests for the NixOS 25.05 release](https://hydra.nixos.org/job/nixos/release-25.05/tested#tabs-constituents)
-Artifacts successfully built with Hydra are published to cache at
+Artifacts successfully built with Hydra are published to cache at https://cache.nixos.org/.
-https://cache.nixos.org/. When successful build and test criteria are
+When successful build and test criteria are met, the Nixpkgs expressions are distributed via [Nix channels](https://nix.dev/manual/nix/stable/command-ref/nix-channel.html).
 met, the Nixpkgs expressions are distributed via [Nix
 channels](https://nix.dev/manual/nix/stable/command-ref/nix-channel.html).
 # Contributing
-Nixpkgs is among the most active projects on GitHub. While thousands
+Nixpkgs is among the most active projects on GitHub.
-of open issues and pull requests might seem a lot at first, it helps
+While thousands of open issues and pull requests might seem a lot at first, it helps consider it in the context of the scope of the project.
-consider it in the context of the scope of the project. Nixpkgs
+Nixpkgs describes how to build tens of thousands of pieces of software and implements a Linux distribution.
-describes how to build tens of thousands of pieces of software and implements a
+The [GitHub Insights](https://github.com/NixOS/nixpkgs/pulse) page gives a sense of the project activity.
 Linux distribution. The [GitHub Insights](https://github.com/NixOS/nixpkgs/pulse)
 page gives a sense of the project activity.
-Community contributions are always welcome through GitHub Issues and
+Community contributions are always welcome through GitHub Issues and Pull Requests.
 Pull Requests.
-For more information about contributing to the project, please visit
+For more information about contributing to the project, please visit the [contributing page](CONTRIBUTING.md).
 the [contributing page](CONTRIBUTING.md).
 # Donations
-The infrastructure for NixOS and related projects is maintained by a
+The infrastructure for NixOS and related projects is maintained by a nonprofit organization, the [NixOS Foundation](https://nixos.org/nixos/foundation.html).
-nonprofit organization, the [NixOS
+To ensure the continuity and expansion of the NixOS infrastructure, we are looking for donations to our organization.
 Foundation](https://nixos.org/nixos/foundation.html). To ensure the
 continuity and expansion of the NixOS infrastructure, we are looking
 for donations to our organization.
-You can donate to the NixOS foundation through [SEPA bank
+You can donate to the NixOS foundation through [SEPA bank transfers](https://nixos.org/donate.html) or by using Open Collective:
 transfers](https://nixos.org/donate.html) or by using Open Collective:
 <a href="https://opencollective.com/nixos#support"><img src="https://opencollective.com/nixos/tiers/supporter.svg?width=890" /></a>
@ -93,9 +79,7 @@ transfers](https://nixos.org/donate.html) or by using Open Collective:
 Nixpkgs is licensed under the [MIT License](COPYING).
-Note: MIT license does not apply to the packages built by Nixpkgs,
+Note:
-merely to the files in this repository (the Nix expressions, build
+MIT license does not apply to the packages built by Nixpkgs, merely to the files in this repository (the Nix expressions, build scripts, NixOS modules, etc.).
-scripts, NixOS modules, etc.). It also might not apply to patches
+It also might not apply to patches included in Nixpkgs, which may be derivative works of the packages to which they apply.
-included in Nixpkgs, which may be derivative works of the packages to
+The aforementioned artifacts are all covered by the licenses of the respective packages.
 which they apply. The aforementioned artifacts are all covered by the
 licenses of the respective packages.
--- a/doc/README.md
+++ b/doc/README.md
@ -62,13 +62,15 @@ Use [`devmode`](../pkgs/by-name/de/devmode/README.md) for a live preview when ed
 Once you have a successful build, you can open the relevant HTML (path mentioned above) in a browser along with the anchor, and observe the redirection.
-Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload. This is because browsers do not re-run client JS code when only the anchor has changed.
+Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload.
 This is because browsers do not re-run client JS code when only the anchor has changed.
 ## Syntax
 As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
-Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
+Additional syntax extensions are available, all of which can be used in NixOS option documentation.
 The following extensions are currently used:
 #### Tables
@ -76,7 +78,8 @@ Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gf
 #### Anchors
-Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
+Explicitly defined **anchors** on headings, to allow linking to sections.
 These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
 It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
@ -99,18 +102,21 @@ They are defined using a hybrid of the link syntax with the attributes syntax kn
 #### Automatic links
-If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.
+If you **omit a link text** for a link pointing to a section, the text will be substituted automatically.
 For example `[](#chap-contributing)`.
 This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
 #### HTML
-Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
+Inlining HTML is not allowed.
 Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
 #### Roles
-If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
+If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``.
 The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
 Please keep the `manpage-urls.json` file alphabetically sorted.
 A few markups for other kinds of literals are also available:
@ -123,7 +129,8 @@ A few markups for other kinds of literals are also available:
 These literal kinds are used mostly in NixOS option documentation.
-This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
+This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point).
 Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
 They are handled by `myst_role` defined per renderer. <!-- reverse references in code -->
 #### 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.
+- Metavariables are in emphasized code spans: ``` *`arg1`* ```.
- Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
+  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
--- 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,
+Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided, while some functions *may still be needed*.
 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.
--- 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.
--- 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.
+- Absolute paths are represented with the Nix [path value type].
- 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.
+  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 `./`.
 <details>
 <summary>Arguments</summary>
- (+) 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.
 <details>
 <summary>Arguments</summary>
- (+) 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.
 <details>
 <summary>Arguments</summary>
 - (+) 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.
+  - (-) We could just not handle such cases, e.g. `equals "foo" "foo/bar/.. == false`.
-    - (+) 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.
+    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.
 <details>
 <summary>Arguments</summary>
- (+) 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.
 </details>
--- a/maintainers/README.md
+++ b/maintainers/README.md
@ -1,71 +1,56 @@
 # Nixpkgs Maintainers
-Unlike other packaging ecosystems, the maintainer doesn't have exclusive
+Unlike other packaging ecosystems, the maintainer doesn't have exclusive control over the packages and modules they maintain.
-control over the packages and modules they maintain. This more fluid approach
+This more fluid approach is one reason why we scale to so many packages.
 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
+The main responsibility of a maintainer is to keep the packages they maintain in a functioning state, and keep up with updates.
-in a functioning state, and keep up with updates. In order to do that, they
+In order to do that, they are empowered to make decisions over the packages they maintain.
 are empowered to make decisions over the packages they maintain.
-That being said, the maintainer is not alone proposing changes to the
+That being said, the maintainer is not alone proposing changes to the packages.
-packages. Anybody (both bots and humans) can send PRs to bump or tweak the
+Anybody (both bots and humans) can send PRs to bump or tweak the package.
 package.
-We also allow other non-maintainer committers to merge changes to 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.
 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
+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).
-changes not endorsed by a package maintainer (which may be themselves). This should leave enough time
+This should leave enough time for the maintainers to provide feedback.
 for the maintainers to provide feedback.
-For critical packages, this convention needs to be negotiated with the
+For critical packages, this convention needs to be negotiated with the maintainer.
-maintainer. A critical package is one that causes mass-rebuild, or where an
+A critical package is one that causes mass-rebuild, or where an author is listed in the [`OWNERS`](../ci/OWNERS) file.
 author is listed in the [`OWNERS`](../ci/OWNERS) file.
-In case of critical security updates, the [security team](https://nixos.org/community/teams/security) might override these
+In case of critical security updates, the [security team](https://nixos.org/community/teams/security) might override these heuristics in order to get the fixes in as fast as possible.
 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
+In case of conflict, the maintainer takes priority and is allowed to revert the changes.
-the changes. This can happen for example if the maintainer was on holiday.
+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
+We encourage people who care about a package to assign themselves as a maintainer.
-maintainer. Commit access to the Nixpkgs repository is not required for that.
+Commit access to the Nixpkgs repository is not required for that.
-In order to do so, add yourself to the
+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.
 [`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
+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
 you become a maintainer of a package, for example), make your change to
 `maintainer-list.nix` in a separate commit titled `maintainers: add <name>`.
 ### How to lose maintainer status
-Maintainers who have become inactive on a given package can be removed. This
+Maintainers who have become inactive on a given package can be removed.
-helps us keep an accurate view of the state of maintenance in Nixpkgs.
+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
+The inactivity measure is currently not strictly enforced.
-look at it if we notice that the author hasn't reacted to package-related
+We would typically look at it if we notice that the author hasn't reacted to package-related notifications for more than 3 months.
 notifications for more than 3 months.
-Removing the maintainer happens by making a PR on the package, adding that
+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.
 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
+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.
 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)
+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).
 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
+[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.
 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/)
+[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.
 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
+When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the following checks should be performed:
 checks should be performed:
- If the user has specified a GPG key, verify that the commit is
+- If the user has specified a GPG key, verify that the commit is signed by their key.
  signed by their key.
-  First, validate that the commit adding the maintainer is signed by
+  First, validate that the commit adding the maintainer is signed by the key the maintainer listed.
-  the key the maintainer listed. Check out the pull request and
+  Check out the pull request and compare its signing key with the listed key in the commit.
  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
+  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.
  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
+  and validate that there is a `Good signature` and the printed key matches the user's submitted key.
  matches the user's submitted key.
-  Note: GitHub's "Verified" label does not display the user's full 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.
  fingerprint, and should not be used for validating the key matches.
- If the user has specified a `github` account name, ensure they have
+- If the user has specified a `github` account name, ensure they have also specified a `githubId` and verify the two match.
  also specified a `githubId` and verify the two match.
-  Maintainer entries that include a `github` field must also include
+  Maintainer entries that include a `github` field must also include their `githubId`.
-  their `githubId`. People can and do change their GitHub name
+  People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer.
  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
+  First, make sure that the listed GitHub handle matches the author of the commit.
  the commit.
-  Then, visit the URL `https://api.github.com/users/ghost` and
+  Then, visit the URL `https://api.github.com/users/ghost` and validate that the `id` field matches the provided `githubId`.
  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)
+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.
 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
+For example, some teams will represent a business or other group which wants to carefully track its members.
-wants to carefully track its members. Other teams may be very open about
+Other teams may be very open about who can join, and allow anybody to participate.
 who can join, and allow anybody to participate.
-When reviewing changes to a team, read the team's scope and the context
+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.
 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
+In any case, request reviews from the existing team members.
-lists no specific membership policy, feel free to merge changes to the
+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.
 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
+*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.
 to the team without an approval by at least one existing member.
 # Maintainer scripts
-Various utility scripts, which are mainly useful for nixpkgs maintainers,
+Various utility scripts, which are mainly useful for nixpkgs maintainers, are available under `./scripts/`.
-are available under `./scripts/`.  See its [README](./scripts/README.md)
+See its [README](./scripts/README.md) for further information.
 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`
+When merging pull requests, care must be taken to reduce impact to the `master` branch.
-branch. If a commit breaks evaluation, it will affect Ofborg evaluation results
+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.
 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
+One approach to avoid merging such problematic changes is to wait for successful Ofborg evaluation.
-successful Ofborg evaluation. Additionally, using tools like
+Additionally, using tools like [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) can help spot issues early, before Ofborg finishes evaluation.
 [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,
+In general breaking changes to `master` and `staging` branches are permitted, as long as they are documented in the release notes.
-as long as they are documented in the release notes. Though restrictions might
+Though restrictions might apply towards the end of a NixOS release cycle, due to our feature freeze mechanism.
-apply towards the end of a NixOS release cycle, due to our feature freeze
+This is to avoid large-scale breakages shortly before and during a Zero Hydra Failures (ZHF) campaign.
-mechanism. This is to avoid large-scale breakages shortly before and during
+These restrictions also intend to decrease the likelihood of a delayed NixOS release.
-a Zero Hydra Failures (ZHF) campaign. These restrictions also intend to
+The feature freeze period is documented in the announcement of each release schedule.
 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
+> These are some example changes and if they are considered a breaking change during a freeze period:
 > during a freeze period:
 >
-> - `foo: 1.2.3 -> 1.2.4` - Assuming this package follows semantic versioning
+> - `foo: 1.2.3 -> 1.2.4`:
->   and none of its dependent packages fail to build because of this change, it
+>   Assuming this package follows semantic versioning and none of its dependent packages fail to build because of this change, it can be safely merged.
->   can be safely merged. Otherwise, if it can be confirmed that there is no
+>   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.
->   major change in its functionality or API, but only adding new features or
+> - `unmaintained-software: drop`:
->   fixing bugs, it
+>   If this PR removes a leaf package or the removal doesn't otherwise break other packages, it can be merged.
->   can also be merged.
+> - `cool-tool: rename from fancy-tool`:
-> - `unmaintained-software: drop` - If this PR removes a leaf package or the
+>   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.
->   removal doesn't otherwise break other packages, it can be merged.
+> - `libpopular: 4.3.2 -> 5.0.0`:
-> - `cool-tool: rename from fancy-tool` - As long as this PR replaces all
+>   If this PR would trigger many rebuilds and/or target `staging`, it should probably be delayed until after the freeze-period is over.
->   references to the old attribute name with the new name and adds an alias,
+>   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.
->   it can be merged.
+>   If a PR includes important changes, such as security fixes, it should be brought up to release managers.
-> - `libpopular: 4.3.2 -> 5.0.0` - If this PR would trigger many rebuilds
+> - `nixos/transmission: refactor`:
->   and/or target `staging`, it should probably be delayed until after the
+>   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.
->   freeze-period is over. Alternatively, if this PR is for a popular package
+>   However, it should be accepted if the current behavior is considered broken and is fixed by the PR.
 >   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.
--- 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,
+This folder contains various executable scripts for nixpkgs maintainers, and supporting data or nixlang files as needed.
 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
+`get-maintainer.sh [selector] value` returns a JSON object describing a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`.
 a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`.
-This allows looking up a maintainer's attrset (including GitHub and Matrix
+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
 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;
+  attributes of the maintainer's object, matched exactly; see [`maintainer-list.nix`] for the fields' definition.
  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
+Outputs a JSON object on stdout mapping GitHub usernames to the attributes that they would be getting pinged for.
 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)`)
+`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}"`.
 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.
--- 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,
+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).
 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.
--- 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
+Currently `nixpkgs` builds most of it's packages using bootstrap seed binaries (without the reliance on external inputs):
 binaries (without the reliance on external inputs):
- `bootstrap-tools`: an archive with the compiler toolchain and other
+- `bootstrap-tools`: an archive with the compiler toolchain and other helper tools enough to build the rest of the `nixpkgs`.
-  helper tools enough to build the rest of the `nixpkgs`.
+- initial binaries needed to unpack `bootstrap-tools.*`.
- initial binaries needed to unpack `bootstrap-tools.*`. On `linux`
+  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.
  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
+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.
 `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
+This document describes the procedure of updating bootstrap files in `nixpkgs`.
 `nixpkgs`.
 ## How to request the bootstrap seed update
-To get the tarballs updated let's use an example `i686-unknown-linux-gnu`
+To get the tarballs updated let's use an example `i686-unknown-linux-gnu` target:
 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
+2. Test the update locally. I'll build local `hello` derivation with the result:
   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`
+   For `riscv64-unknown-linux-gnu` the `/etc/nixos/configuration.nix` entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`.
   entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`.
-3. Propose the commit as a PR to update bootstrap tarballs, tag people
+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.
   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
+The procedure to add a new target is very similar to the update procedure.
-procedure. The only difference is that you need to set up a new job to
+The only difference is that you need to set up a new job to build the `bootstrapFiles`.
-build the `bootstrapFiles`. To do that you will need the following:
+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
+   This will populate `pkgsCross.$target` attribute set.
-   dealing with `bootstrapFiles` upload you probably already have it.
+   If you are dealing with `bootstrapFiles` upload you probably already have it.
-2. Add your new target to
+2. Add your new target to `pkgs/stdenv/linux/make-bootstrap-tools-cross.nix`.
-   `pkgs/stdenv/linux/make-bootstrap-tools-cross.nix`. This will add a
+   This will add a new hydra job to `nixpkgs:cross-trunk` jobset.
   new hydra job to `nixpkgs:cross-trunk` jobset.
 3. Wait for a hydra to build your bootstrap tarballs.
-4. Add your new target to
+4. Add your new target to `maintainers/scripts/bootstrap-files/refresh-tarballs.bash` around `CROSS_TARGETS=()`.
   `maintainers/scripts/bootstrap-files/refresh-tarballs.bash` around
   `CROSS_TARGETS=()`.
-5. Add your new target to `pkgs/stdenv/linux/default.nix` and follow
+5. Add your new target to `pkgs/stdenv/linux/default.nix` and follow standard bootstrap seed update procedure above.
   standard bootstrap seed update procedure above.
 ## Bootstrap files job definitions
 There are two types of bootstrap files:
- natively built `stdenvBootstrapTools.build` hydra jobs in
+- natively built `stdenvBootstrapTools.build` hydra jobs in [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs) jobset.
-  [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs)
+  Incomplete list of examples is:
  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
+- cross-built by `bootstrapTools.build` hydra jobs in [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs) jobset.
-  [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs)
+  Incomplete list of examples is:
  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
+The `.build` job contains `/on-server/` subdirectory with binaries to be uploaded to `tarballs.nixos.org`.
 be uploaded to `tarballs.nixos.org`.
 The files are uploaded to `tarballs.nixos.org` by writers to `S3` store.
--- a/nixos/README.md
+++ b/nixos/README.md
@ -1,12 +1,12 @@
 # NixOS
-NixOS is a Linux distribution based on the purely functional package
+NixOS is a Linux distribution based on the purely functional package management system Nix.
-management system Nix.  More information can be found at
+More information can be found at https://nixos.org/nixos and in the manual in doc/manual.
 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=<path to your local nixpkgs folder> --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=<path to your local nixpkgs folder> --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:
--- 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
--- 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.
+* Is the package ready for general use?
-* 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.
+  We don't want to include projects that are too immature or are going to be abandoned immediately.
-* 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.
+  In case of doubt, check with upstream.
-* 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.
+* Does the project have a clear license statement?
-* 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.
+  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:
+* Packages typically used with untrusted data should have a maintained and responsible upstream.
-  * Any package which does not follow upstream security policies should be considered vulnerable. In particular, packages that vendor or fork web engines like Blink, Gecko or Webkit need to keep up with the frequent updates of those projects.
+  For example:
-  * 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.
+  * 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. Test if the changes introduced any issues by running `nix-env -qaP -f . --show-trace`.
-1. Commit the changes. Explain again why the package was removed. If it was declared discontinued upstream, add a link to the source.
+   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.
+* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs.
-* 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.
+  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.