nathan/nixpkgs
1
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2026-06-05 21:03:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

**/README.md: one sentence per line

Browse Source 
As documented in doc/README.md.
This commit is contained in:
Wolfgang Walther
2025-06-29 18:33:08 +02:00
parent 2369d96548
commit b4532efe93
13 changed files with 392 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
CONTRIBUTING.md
View File

@@ -125,7 +125,8 @@ This section describes in some detail how changes can be made and proposed with
### Pull request template
[pr-template]: #pull-request-template
The pull request template helps determine what steps have been made for a contribution so far, and will help guide maintainers on the status of a change. The motivation section of the PR should include any extra details the title does not address and link any existing issues related to the pull request.
The pull request template helps determine what steps have been made for a contribution so far, and will help guide maintainers on the status of a change.
The motivation section of the PR should include any extra details the title does not address and link any existing issues related to the pull request.
When a PR is created, it will be pre-populated with some checkboxes detailed below:
@@ -149,15 +150,22 @@ Please enable sandboxing **before** building the package by adding the following
#### Built on platform(s)
Many Nix packages are designed to run on multiple platforms. As such, it’s important to let the maintainer know which platforms your changes have been tested on. It’s not always practical to test a change on all platforms, and is not required for a pull request to be merged. Only check the systems you tested the build on in this section.
Many Nix packages are designed to run on multiple platforms.
As such, it’s important to let the maintainer know which platforms your changes have been tested on.
It’s not always practical to test a change on all platforms, and is not required for a pull request to be merged.
Only check the systems you tested the build on in this section.
#### Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
Packages with automated tests are much more likely to be merged in a timely fashion because it doesn’t require as much manual testing by the maintainer to verify the functionality of the package. If there are existing tests for the package, they should be run to verify your changes do not break the tests. Tests can only be run on Linux. For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests).
Packages with automated tests are much more likely to be merged in a timely fashion because it doesn’t require as much manual testing by the maintainer to verify the functionality of the package.
If there are existing tests for the package, they should be run to verify your changes do not break the tests.
Tests can only be run on Linux.
For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests).
#### Tested compilation of all pkgs that depend on this change using `nixpkgs-review`
If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still compile correctly. The `nixpkgs-review` utility can look for and build all dependencies either based on uncommitted changes with the `wip` option or specifying a GitHub pull request number.
If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still compile correctly.
The `nixpkgs-review` utility can look for and build all dependencies either based on uncommitted changes with the `wip` option or specifying a GitHub pull request number.
Review changes from pull request number 12345:
@@ -185,23 +193,23 @@ nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"
#### Tested execution of all binary files (usually in `./result/bin/`)
It’s important to test any executables generated by a build when you change or create a package in nixpkgs. This can be done by looking in `./result/bin` and running any files in there, or at a minimum, the main executable for the package. For example, if you make a change to texlive, you probably would only check the binaries associated with the change you made rather than testing all of them.
It’s important to test any executables generated by a build when you change or create a package in nixpkgs.
This can be done by looking in `./result/bin` and running any files in there, or at a minimum, the main executable for the package.
For example, if you make a change to texlive, you probably would only check the binaries associated with the change you made rather than testing all of them.
#### Meets Nixpkgs contribution standards
The last checkbox is about whether it fits the guidelines in this `CONTRIBUTING.md` file. This document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
The last checkbox is about whether it fits the guidelines in this `CONTRIBUTING.md` file.
This document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc...
Everyone should read and understand the standards the community has for contributing before submitting a pull request.
### Rebasing between branches (i.e. from master to staging)
[rebase]: #rebasing-between-branches-ie-from-master-to-staging
From time to time, changes between branches must be rebased, for example, if the
number of new rebuilds they would cause is too large for the target branch.
From time to time, changes between branches must be rebased, for example, if the number of new rebuilds they would cause is too large for the target branch.
In the following example, we assume that the current branch, called `feature`,
is based on `master`, and we rebase it onto the merge base between
`master` and `staging` so that the PR can be retargeted to
`staging`. The example uses `upstream` as the remote for `NixOS/nixpkgs.git`
while `origin` is the remote you are pushing to.
In the following example, we assume that the current branch, called `feature`, is based on `master`, and we rebase it onto the merge base between `master` and `staging` so that the PR can be retargeted to `staging`.
The example uses `upstream` as the remote for `NixOS/nixpkgs.git` while `origin` is the remote you are pushing to.
```console
@@ -211,14 +219,10 @@ git rebase --onto upstream/staging... upstream/master
git push origin feature --force-with-lease
```
The syntax `upstream/staging...` is equivalent to `upstream/staging...HEAD` and
stands for the merge base between `upstream/staging` and `HEAD` (hence between
`upstream/staging` and `upstream/master`).
The syntax `upstream/staging...` is equivalent to `upstream/staging...HEAD` and stands for the merge base between `upstream/staging` and `HEAD` (hence between `upstream/staging` and `upstream/master`).
Then change the base branch in the GitHub PR using the *Edit* button in the upper
right corner, and switch from `master` to `staging`. *After* the PR has been
retargeted it might be necessary to do a final rebase onto the target branch, to
resolve any outstanding merge conflicts.
Then change the base branch in the GitHub PR using the *Edit* button in the upper right corner, and switch from `master` to `staging`.
*After* the PR has been retargeted it might be necessary to do a final rebase onto the target branch, to resolve any outstanding merge conflicts.
```console
# Rebase onto target branch
@@ -272,13 +276,19 @@ To manually create a backport pull request, follow [the standard pull request pr
> [!Warning]
> The following section is a draft, and the policy for reviewing is still being discussed in issues such as [#11166](https://github.com/NixOS/nixpkgs/issues/11166) and [#20836](https://github.com/NixOS/nixpkgs/issues/20836).
The Nixpkgs project receives a fairly high number of contributions via GitHub pull requests. Reviewing and approving these is an important task and a way to contribute to the project.
The Nixpkgs project receives a fairly high number of contributions via GitHub pull requests.
Reviewing and approving these is an important task and a way to contribute to the project.
The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger. Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue. GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests. We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone).
The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger.
Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue.
GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests.
We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone).
When reviewing a pull request, please always be nice and polite. Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work.
When reviewing a pull request, please always be nice and polite.
Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work.
GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.
GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments.
The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.
When doing a review:
- Aim to drive the proposal to a timely conclusion.
@@ -298,34 +308,36 @@ If the related change is essential for the contribution at hand, make clear why
Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.
All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.
All the review template samples provided in this section are generic and meant as examples.
Their usage is optional and the reviewer is free to adapt them to their liking.
To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview].
If a pull request contains documentation changes that might require feedback from the documentation team, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on the pull request.
If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic. They will give you information about the reviewing process. The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints.
If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic.
They will give you information about the reviewing process.
The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints.
Container system, boot system and library changes are some examples of the pull requests fitting this category.
## How to merge pull requests yourself
[pr-merge]: #how-to-merge-pull-requests
To streamline automated updates, leverage the nixpkgs-merge-bot by simply commenting `@NixOS/nixpkgs-merge-bot merge`. The bot will verify if the following conditions are met, refusing to merge otherwise:
To streamline automated updates, leverage the nixpkgs-merge-bot by simply commenting `@NixOS/nixpkgs-merge-bot merge`.
The bot will verify if the following conditions are met, refusing to merge otherwise:
- the PR author should be @r-ryantm or a Nixpkgs committer;
- the commenter that issued the command should be among the package maintainers;
- the package should reside in `pkgs/by-name`.
Further, nixpkgs-merge-bot will ensure all ofBorg checks (except the Darwin-related ones) are successfully completed before merging the pull request. Should the checks still be underway, the bot patiently waits for ofBorg to finish before attempting the merge again.
Further, nixpkgs-merge-bot will ensure all ofBorg checks (except the Darwin-related ones) are successfully completed before merging the pull request.
Should the checks still be underway, the bot patiently waits for ofBorg to finish before attempting the merge again.
For other pull requests, please see [I opened a PR, how do I get it merged?](#i-opened-a-pr-how-do-i-get-it-merged).
In case the PR is stuck waiting for the original author to apply a trivial
change (a typo, capitalisation change, etc.) and the author allowed the members
to modify the PR, consider applying it yourself (or commit the existing review
suggestion). You should pay extra attention to make sure the addition doesn't go
against the idea of the original PR and would not be opposed by the author.
In case the PR is stuck waiting for the original author to apply a trivial change (a typo, capitalisation change, etc.) and the author allowed the members to modify the PR, consider applying it yourself (or commit the existing review suggestion).
You should pay extra attention to make sure the addition doesn't go against the idea of the original PR and would not be opposed by the author.
<!--
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;
**for anything else, ask the [Staging room](https://matrix.to/#/#staging:nixos.org) first**.
The `staging-next` branch should then only receive changes that fix Hydra builds; **for anything else, ask the [Staging room](https://matrix.to/#/#staging:nixos.org) first**.
Once it is verified that there are no major regressions, it is merged into `master` using [a pull request](https://github.com/NixOS/nixpkgs/pulls?q=head%3Astaging-next).
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
formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).
CI [enforces](./.github/workflows/check-format.yml) all Nix files to be 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`,
you can also set it up to automatically format the file with `treefmt` on save.
If you're starting your editor in `nix-shell` or `nix develop`, you can also set it up to automatically format the file with `treefmt` on save.
If you have any problems with formatting, please ping the
[formatting team](https://nixos.org/community/teams/formatting/) via
[@NixOS/nix-formatting](https://github.com/orgs/NixOS/teams/nix-formatting).
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).
### 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.
- Get non-committers to review/approve. Many committers filter open PRs for low-hanging fruit that are already been reviewed.
- Wait.
Reviewers frequently browse open PRs and may happen to run across yours and take a look.
- Get non-committers to review/approve.
Many committers filter open PRs for low-hanging fruit that are already been reviewed.
- [@-mention](https://github.blog/news-insights/mention-somebody-they-re-notified/) someone and ask them nicely
- Post in one of the channels made for this purpose if there has been no activity for at least one week
- The current "PRs ready for review" or "PRs already reviewed" threads in the [NixOS Discourse](https://discourse.nixos.org/c/dev/14) (of course choose the one that applies to your situation)
@@ -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.