CONTRIBUTING.md at master · pyrox.dev/nixpkgs

pyrox.dev / nixpkgs
lol
nixpkgs / CONTRIBUTING.md
at master 46 kB view raw view rendered
  1# Contributing to Nixpkgs
  2
  3This document is for people wanting to contribute to Nixpkgs.
  4This involves changes that are proposed using [GitHub](https://github.com) [pull requests](https://docs.github.com/pull-requests) to the [Nixpkgs repository](https://github.com/nixos/nixpkgs).
  5
  6A GitHub account is recommended, which you can sign up for [here](https://github.com/signup).
  7See [here](https://discourse.nixos.org/t/about-the-patches-category/477) for how to contribute without a GitHub account.
  8
  9This document assumes that you already know how to use GitHub and Git.
 10If that's not the case, we recommend learning about it [here](https://docs.github.com/en/get-started/quickstart/hello-world).
 11
 12## Overview
 13[overview]: #overview
 14
 15This file contains general contributing information.
 16More specific information about individual parts of Nixpkgs can be found here:
 17- [`doc`](./doc/README.md): Sources and infrastructure for the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/)
 18- [`lib`](./lib/README.md): Sources and documentation of the [library functions](https://nixos.org/manual/nixpkgs/stable/#chap-functions)
 19- [`maintainers`](./maintainers/README.md): Nixpkgs maintainer and team listings, maintainer scripts
 20- [`nixos`](./nixos/README.md): Implementation of [NixOS](https://nixos.org/manual/nixos/stable/)
 21- [`pkgs`](./pkgs/README.md): Package and [builder](https://nixos.org/manual/nixpkgs/stable/#part-builders) definitions
 22
 23# How to's
 24
 25## How to create pull requests
 26[pr-create]: #how-to-create-pull-requests
 27
 28This section describes how changes can be proposed with a pull request (PR).
 29
 30> [!Note]
 31> Be aware that contributing implies licensing those contributions under the terms of [COPYING](./COPYING), an MIT-like license.
 32
 330. Set up a local version of Nixpkgs to work with:
 34   1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) the [Nixpkgs repository](https://github.com/nixos/nixpkgs).
 35   1. [Clone the forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) into a local `nixpkgs` directory.
 36   1. [Configure the upstream Nixpkgs repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).
 37
 381. Select the appropriate [base branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches) for the change, as [described here][branch].
 39   If in doubt, use `master`.
 40   This can be changed later by [rebasing][rebase].
 41
 422. Create a new Git branch, ideally such that:
 43   - The name of the branch hints at your change, e.g. `update-hello`.
 44   - The branch contains the most recent base branch.
 45
 46   We'll assume the base branch `master` here.
 47
 48   ```bash
 49   # Make sure you have the latest changes from upstream Nixpkgs
 50   git fetch upstream
 51
 52   # Create and switch to a new branch, based on the base branch in Nixpkgs
 53   git switch --create update-hello upstream/master
 54   ```
 55
 56   To avoid potentially having to download and build many derivations, you can base on a specific [Git commit](https://www.git-scm.com/docs/gitglossary#def_commit) instead:
 57   - The commit of the latest `nixpkgs-unstable` channel, available [here](https://channels.nixos.org/nixpkgs-unstable/git-revision).
 58   - The commit of a local Nixpkgs downloaded using [nix-channel](https://nixos.org/manual/nix/stable/command-ref/nix-channel), available using `nix-instantiate --eval --expr '(import <nixpkgs/lib>).trivial.revisionWithDefault null'`
 59   - If you're using NixOS, the commit of your NixOS installation, available with `nixos-version --revision`.
 60
 61   You can use this commit instead of `upstream/master` in the above command:
 62   ```bash
 63   # Here, b9c03fbb is an example commit from nixpkgs-unstable
 64   git switch --create update-hello b9c03fbb
 65   ```
 66
 673. Make your changes in the local Nixpkgs repository and:
 68   - Adhere to both the [general code conventions][code-conventions], and the relevant [specific code conventions][overview].
 69   - Test the changes.
 70   - If necessary, document the changes.
 71
 72   See the [overview section][overview] for more specific information.
 73
 744. Commit your changes using `git commit`.
 75   Make sure to adhere to the [commit conventions](#commit-conventions).
 76
 77   Repeat the steps 3-4 as many times as necessary.
 78   Advance to the next step once all the commits make sense together.
 79   You can view your commits with `git log`.
 80
 815. Push your commits to your fork of Nixpkgs:
 82   ```
 83   git push --set-upstream origin HEAD
 84   ```
 85
 86   The above command will output a link to directly do the next step:
 87   ```
 88   remote: Create a pull request for 'update-hello' on GitHub by visiting:
 89   remote:      https://github.com/myUser/nixpkgs/pull/new/update-hello
 90   ```
 91
 926. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request) from the new branch in your Nixpkgs fork to the upstream Nixpkgs repository.
 93   Use the branch from step 1 as the PR's base branch.
 94   Go through the [pull request template][pr-template].
 95
 967. Respond to review comments and potentially to CI failures and merge conflicts by updating the PR.
 97   Always keep it in a mergeable state.
 98
 99   The non-technical side of this process is covered in [I opened a PR, how do I get it merged?](#i-opened-a-pr-how-do-i-get-it-merged).
100
101   The [ofborg](https://github.com/NixOS/ofborg) CI system will perform checks to ensure code quality.
102   You can see the results at the bottom of the PR.
103   See [the ofborg Readme](https://github.com/NixOS/ofborg#readme) for more details.
104
105   - To add new commits, repeat steps 3-4 and push the result:
106     ```
107     git push
108     ```
109
110   - To change existing commits, [rewrite the Git history](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
111     Useful Git commands for this are `git commit --patch --amend` and `git rebase --interactive`.
112     With a rewritten history you need to force-push the commits:
113     ```
114     git push --force-with-lease
115     ```
116
117   - If there are merge conflicts, you will have to [rebase the branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) onto the current **base branch**.
118     Sometimes this can be done [on GitHub directly](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch#updating-your-pull-request-branch).
119     To rebase locally:
120     ```
121     git fetch upstream
122     git rebase upstream/master
123     git push --force-with-lease
124     ```
125
126     Use the base branch from step 1 instead of `upstream/master`.
127
128   - If you need to change the base branch, [rebase][rebase].
129
1308. If your PR is merged and [acceptable for releases][release-acceptable], you may [backport][pr-backport] it.
131
132### Pull request template
133[pr-template]: #pull-request-template
134
135The pull request template helps to determine which steps have been taken so far.
136Details not covered by the title and links to existing related issues should go at the top.
137
138When a PR is created, it will be pre-populated with some checkboxes.
139
140#### Tested using sandboxing
141
142When sandbox builds are enabled, Nix will set up an isolated environment for each build process.
143It is used to remove further hidden dependencies set by the build environment, to improve reproducibility.
144This includes access to the network during the build outside of `fetch*` functions and files outside the Nix store.
145Depending on the operating system, access to other resources is blocked as well; see [sandbox](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-sandbox) in the Nix manual for details.
146
147Please test builds with sandboxing enabled, because it is also used in [Hydra](https://nixos.org/hydra).
148
149If you are on Linux, sandboxing is enabled by default.
150On other platforms, sandboxing is disabled by default due to a small performance hit on each build.
151
152Please enable sandboxing **before** building the package by adding the following to `/etc/nix/nix.conf`:
153
154  ```ini
155  sandbox = true
156  ```
157
158#### Built on platform(s)
159
160Many Nix packages are designed to run on multiple platforms.
161As such, it’s important to let the maintainer know which platforms you have tested on.
162It’s not always practical to test all platforms, and it’s not required for a pull request to be merged.
163Only check the platforms you tested the build on in this section.
164
165#### Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
166
167Packages with automated tests are likely merged quicker, because they don’t require as much manual testing.
168If there are existing tests for the package, they should be run.
169NixOS tests can only be run on linux.
170For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests).
171
172#### Tested compilation of all pkgs that depend on this change using `nixpkgs-review`
173
174If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still build.
175It can work on uncommitted changes with the `wip` option or on a specific pull request.
176
177Review changes from pull request number 12345:
178
179```ShellSession
180nix-shell -p nixpkgs-review --run "nixpkgs-review pr 12345"
181```
182
183Alternatively, with flakes (and analogously for the other commands below):
184
185```ShellSession
186nix run nixpkgs#nixpkgs-review -- pr 12345
187```
188
189Review uncommitted changes:
190
191```ShellSession
192nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
193```
194
195Review changes from the last commit:
196
197```ShellSession
198nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"
199```
200
201#### Tested execution of all binary files (usually in `./result/bin/`)
202
203It's important to test a modified package's executables.
204Look into `./result/bin` and run all files in there, or at a minimum, the main executable.
205For 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.
206
207#### Meets Nixpkgs contribution standards
208
209The last checkbox is about whether it fits the guidelines in this `CONTRIBUTING.md` file.
210This document details our standards for commit messages, reviews, licensing of contributions, etc...
211Everyone should read and understand these standards before submitting a pull request.
212
213### Rebasing between branches (i.e. from `master` to `staging`)
214[rebase]: #rebasing-between-branches-ie-from-master-to-staging
215
216Sometimes, changes must be rebased between branches.
217One example is, if the number of rebuilds caused is too large for the original target branch.
218
219In the following example, the current `feature` branch is based on `master`, and we rebase it to have the PR target `staging`.
220We rebase on the _merge base_ between `master` and `staging` to avoid too many local rebuilds.
221
222
223```console
224# Rebase your commits onto the common merge base
225git rebase --onto upstream/staging... upstream/master
226# Force push your changes
227git push origin feature --force-with-lease
228```
229
230The 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`).
231
232Then use the *Edit* button in the upper right corner of the GitHub PR, and switch the base branch from `master` to `staging`.
233*After* the PR has been retargeted, a final rebase onto the target branch might be needed to resolve merge conflicts.
234
235```console
236# Rebase onto target branch
237git rebase upstream/staging
238# Review and fixup possible conflicts
239git status
240# Force push your changes
241git push origin feature --force-with-lease
242```
243
244## How to backport pull requests
245[pr-backport]: #how-to-backport-pull-requests
246
247Once a PR has been merged, a backport to the corresponding `release-YY.MM` branch can be created.
248
249### Automatically backporting changes
250
251> [!Note]
252> You have to be a [Nixpkgs maintainer](./maintainers) to automatically create a backport pull request.
253
254Add the [`backport release-YY.MM` label](https://github.com/NixOS/nixpkgs/labels?q=backport) to the PR on the `master` branch.
255This will cause [a GitHub Action](.github/workflows/backport.yml) to open a new PR to the `release-YY.MM` branch a few minutes later.
256This can be done on both open or already merged pull requests.
257
258### Manually backporting changes
259
260To manually create a backport, follow [the standard pull request process][pr-create], but:
261
262- Use `release-YY.MM` for the base branch, both for the local branch and the pull request.
263
264> [!Warning]
265> Do not use the `nixos-YY.MM` branch.
266> It points to the latest _tested_ release channel commit.
267
268- Instead of manually making and committing the changes, use [`git cherry-pick -x`](https://git-scm.com/docs/git-cherry-pick) for each commit.
269  Use `git cherry-pick -x <commit>` when the reason is obvious, for example for minor version bumps and fixes.
270  Otherwise, use `git cherry-pick -xe <commit>` to add a reason for the backport.
271  Here is [an example](https://github.com/nixos/nixpkgs/commit/5688c39af5a6c5f3d646343443683da880eaefb8).
272
273> [!Warning]
274> Ensure the commits exist on the `master` branch.
275> In the case of squashed or rebased merges, the commit hash will change and the new commits can be found in the merge message at the bottom of the `master` pull request.
276
277- In the pull request description, link to the original pull request to `master`.
278  The pull request title should include `[YY.MM]` matching the release you're backporting to.
279
280## How to review pull requests
281[pr-review]: #how-to-review-pull-requests
282
283The Nixpkgs project receives a high number of pull requests.
284Anyone may review and approve PRs and it is an important contribution to the project.
285
286The high change rate makes any PR that remains open for too long subject to merge conflicts.
287To avoid extra work, reviewing PRs timely and being responsive is key.
288GitHub provides sort filters to see the [most recently updated](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) pull requests.
289We 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+no%3Aproject+no%3Aassignee+no%3Amilestone).
290
291Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work.
292Always be nice and polite.
293
294GitHub provides reactions for quick feedback to pull requests or comments.
295The thumb-down reaction should be used with care and, if possible, accompanied with explanation for the submitter to improve their contribution.
296
297When doing a review:
298- Aim to drive the proposal to a timely conclusion.
299- Focus on the proposed changes and keep the scope narrow.
300- Help the contributor prioritise their efforts towards getting their change merged.
301
302If you find anything related that could be improved but is not immediately required for acceptance, consider:
303- Implementing the changes yourself in a follow-up pull request,
304- Tracking your idea in an issue,
305- Offering to review a follow-up pull request,
306- Making concrete [suggestions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) in the same pull request.
307
308For example, follow-up changes could involve refactoring code in the affected files.
309
310But please remember not to make such additional considerations a blocker, and communicate that to the contributor, for example by following the [conventional comments](https://conventionalcomments.org) pattern.
311If the related change is essential for the contribution at hand, make clear why you think it is important to address that first.
312
313Pull 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.
314
315All the review templates provided are generic examples.
316Their usage is optional and the reviewer is free to adapt them.
317
318To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview].
319
320If 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.
321
322If you have 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.
323The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests or git-blaming the code can give some hints.
324
325## How to merge pull requests yourself
326[pr-merge]: #how-to-merge-pull-requests
327
328You can invoke the nixpkgs-merge-bot by commenting `@NixOS/nixpkgs-merge-bot merge`.
329The bot will verify the following conditions, refusing to merge otherwise:
330
331- the PR author should be @r-ryantm or a Nixpkgs committer;
332- the invoker should be among the package maintainers;
333- the package should reside in `pkgs/by-name`.
334
335Further, nixpkgs-merge-bot will ensure all CI checks and the ofborg builds for Linux have successfully completed before merging the pull request.
336Should the checks still be underway, the bot will wait for them to finish before attempting the merge again.
337
338For 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).
339
340In case the PR is stuck waiting for the author to apply a trivial change and the author allowed members to modify the PR, consider applying it yourself.
341You 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.
342
343Please see the discussion in [GitHub nixpkgs issue #321665](https://github.com/NixOS/nixpkgs/issues/321665) for information on how to proceed to be granted this level of access.
344
345As a maintainer, when you leave the Nix community, please create an issue or post on [Discourse](https://discourse.nixos.org) with references to the packages and modules you maintained, so they can be taken over by other contributors.
346
347# Flow of merged pull requests
348
349After a pull request is merged, it eventually makes it to [Hydra](https://hydra.nixos.org).
350Hydra regularly evaluates and builds Nixpkgs, updating [the official channels](https://channels.nixos.org) when their jobs succeed.
351See [Nix Channel Status](https://status.nixos.org) for the current channel states.
352
353Our primary development branches and their related channels are:
354
355- `master`: The main branch, used for the unstable channels `nixos-unstable`, `nixos-unstable-small` and `nixpkgs-unstable`.
356- `release-YY.MM`: The release branches, used for the stable channels `nixos-YY.MM`, `nixos-YY.MM-small` and `nixpkgs-YY.MM-darwin`.
357
358When a channel is updated, its corresponding branch is also updated to the same commit.
359Example: The [`nixpkgs-unstable` branch](https://github.com/nixos/nixpkgs/tree/nixpkgs-unstable) corresponds to the commit from the [`nixpkgs-unstable` channel](https://channels.nixos.org/nixpkgs-unstable).
360
361Nixpkgs is tied to the NixOS release process, which is documented in the [NixOS Release Wiki](https://nixos.github.io/release-wiki/).
362
363See [this section][branch] to know when to use the release branches.
364
365## Staging
366[staging]: #staging
367
368The staging workflow exists to batch Hydra builds of many packages together.
369It is coordinated in the [Staging room](https://matrix.to/#/#staging:nixos.org) on Matrix.
370
371It works by directing commits that cause [mass rebuilds][mass-rebuild] to a separate `staging` branch that isn't directly built by Hydra.
372Regularly, 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).
373The `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**.
374Once it is verified that there are no major regressions, `staging-next` is merged into `master` using [a pull request](https://github.com/NixOS/nixpkgs/issues?q=label%3A%224.workflow%3A+staging%22).
375This is done manually to ensure it's a good use of Hydra's computing resources.
376Since `staging-next` is separate from `staging`, you may merge changes into `staging` at any time.
377
378In order for the `staging` and `staging-next` branches to be up-to-date with the latest commits on `master`, there are regular _automated_ merges from `master` into `staging-next`, and from `staging-next` into `staging`.
379This is implemented using GitHub workflows [here](.github/workflows/periodic-merge-6h.yml) and [here](.github/workflows/periodic-merge-24h.yml).
380
381> [!Note]
382> Changes must be well tested before being merged into any branch.
383> Hydra builds should not be used as a testing platform.
384
385Here is a Git history diagram showing the flow of commits between the three branches:
386```mermaid
387%%{init: {
388    'theme': 'base',
389    'themeVariables': {
390        'gitInv0': '#ff0000',
391        'gitInv1': '#ff0000',
392        'git2': '#ff4444',
393        'commitLabelFontSize': '15px'
394    },
395    'gitGraph': {
396        'showCommitLabel':true,
397        'mainBranchName': 'master',
398        'rotateCommitLabel': true
399    }
400} }%%
401gitGraph
402    commit id:" "
403    branch staging
404    commit id:"  "
405    branch staging-next
406
407    merge master id:"automatic"
408    checkout staging
409    merge staging-next id:"automatic "
410
411    checkout staging-next
412    merge staging type:HIGHLIGHT id:"manual"
413    commit id:"fixup"
414
415    checkout master
416    checkout staging
417    checkout master
418    commit id:"       "
419    checkout staging-next
420    merge master id:"automatic  "
421    checkout staging
422    merge staging-next id:"automatic   "
423
424    checkout staging-next
425    commit id:"fixup "
426    checkout master
427    merge staging-next type:HIGHLIGHT id:"manual (PR)"
428```
429
430
431Here's an overview of the different branches:
432
433| branch | `master` | `staging-next` | `staging` |
434| --- | --- | --- | --- |
435| Used for development | ✔️ | ❌ | ✔️ |
436| Built by Hydra | ✔️ | ✔️ | ❌ |
437| [Mass rebuilds][mass-rebuild] | ❌ | ⚠️  Only to fix Hydra builds | ✔️ |
438| Critical security fixes | ✔️ for non-mass-rebuilds | ✔️ for mass-rebuilds | ❌ |
439| Automatically merged into | `staging-next` | `staging` | - |
440| Manually merged into | - | `master` | `staging-next` |
441
442The staging workflow is used for all stable branches with corresponding names:
443- `master`/`release-YY.MM`
444- `staging`/`staging-YY.MM`
445- `staging-next`/`staging-next-YY.MM`
446
447# Conventions
448
449## Branch conventions
450<!-- This section is relevant to both contributors and reviewers -->
451[branch]: #branch-conventions
452
453Most changes should go to `master`, but sometimes other branches should be used instead.
454Use the following decision process to figure out the right branch:
455
456Is the change [acceptable for releases][release-acceptable] and do you wish to have the change in the release?
457- No: Use the `master` branch, do not backport the pull request.
458- Yes: Can the change be implemented the same way on the `master` and release branches?
459  For example, a package's major version might differ between the `master` and release branches, such that separate security patches are required.
460  - Yes: Use the `master` branch and [backport the pull request](#how-to-backport-pull-requests).
461  - No: Create separate pull requests to the `master` and `release-YY.MM` branches.
462
463If the change causes a [mass rebuild][mass-rebuild], use the `staging` branch instead:
464- Mass rebuilds to `master` should go to `staging` instead.
465- Mass rebuilds to `release-YY.MM` should go to `staging-YY.MM` instead.
466
467See [this section][staging] for how such changes propagate between the branches.
468
469### Changes acceptable for releases
470[release-acceptable]: #changes-acceptable-for-releases
471
472Only changes to _supported_ releases may be accepted.
473The oldest supported release (`YYMM`) can be found using
474```
475nix-instantiate --eval -A lib.trivial.oldestSupportedRelease
476```
477
478The release branches should generally only receive backwards-compatible changes, both for the Nix expressions and derivations.
479Here are some examples of changes that are okay to backport:
480- ✔️ New packages, modules and functions
481- ✔️ Security fixes
482- ✔️ Package version updates
483  - ✔️ Patch versions with fixes
484  - ✔️ Minor versions with new functionality, but no breaking changes
485
486In addition, major package version updates with breaking changes are also acceptable for:
487- ✔️ Services that would fail without up-to-date client software, such as `spotify`, `steam`, and `discord`
488- ✔️ Security critical applications, such as `firefox` and `chromium`
489
490### Changes causing mass rebuilds
491[mass-rebuild]: #changes-causing-mass-rebuilds
492
493Which changes cause mass rebuilds is not formally defined.
494In order to help the decision, CI automatically assigns [`rebuild` labels](https://github.com/NixOS/nixpkgs/labels?q=rebuild) to pull requests based on the number of packages they cause rebuilds for.
495As a rule of thumb, if the number of rebuilds is **500 or more**, consider targeting the `staging` branch instead of `master`; if the number is **1000 or more**, the pull request causes a mass rebuild, and should target the `staging` branch.
496See [previously merged pull requests to the staging branches](https://github.com/NixOS/nixpkgs/issues?q=base%3Astaging+-base%3Astaging-next+is%3Amerged) to get a sense for what changes are considered mass rebuilds.
497
498## Commit conventions
499[commit-conventions]: #commit-conventions
500
501- Create one commit for each logical unit.
502
503- If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case.
504  Use `git rebase -i`.
505  See [Squashing Commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) for additional information.
506
507- 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).
508
509- When adding yourself to `maintainer-list.nix`, make a separate commit with the message `maintainers: add <handle>`.
510  Add the commit before those making changes to the package or module.
511  See [Nixpkgs Maintainers](./maintainers/README.md) for details.
512
513- Make sure you read about any commit conventions specific to the area you're touching.
514  See:
515  - [Commit conventions](./doc/README.md#commit-conventions) for changes to `doc`, the Nixpkgs manual.
516  - [Commit conventions](./lib/README.md#commit-conventions) for changes to `lib`.
517  - [Commit conventions](./nixos/README.md#commit-conventions) for changes to `nixos`.
518  - [Commit conventions](./pkgs/README.md#commit-conventions) for changes to `pkgs`.
519
520### Writing good commit messages
521[writing-good-commit-messages]: #writing-good-commit-messages
522
523It's important to include relevant information in the *commit message*, so others can later understand *why* a change was made.
524While this potentially can be understood by reading code, PR discussion or upstream changes, doing so often requires a lot of work.
525
526Simple package version updates need to include the attribute name, old and new versions, as well as a reference to the release notes or changelog.
527Package upgrades with more extensive changes require more verbose commit messages.
528
529## Review and Merge conventions
530
531Comments on Pull Requests are considered non-blocking by default.
532Every blocking comment must be explicitly marked as such by using GitHub's "Request Changes" review type.
533A reviewer who submits a blocking review should be available for discussion and re-review.
534An abandoned review may be dismissed after reasonable time was given at the discretion of the merger.
535
536All suggestions for change, blocking or not, should be acknowledged before merge.
537This can happen implicitly by applying the suggestion, or explicitly by rejecting it.
538
539To make changes on commit structure and commit messages or apply simple suggestions, committers are encouraged to [checkout the PR](https://cli.github.com/manual/gh_pr_checkout) and push directly to the contributor's branch before merging.
540Committers will carefully weigh the cost of another review cycle against the feelings of the contributor when pushing to their branch.
541They should also transparently communicate which changes they made.
542If a contributor does not want committers to push to their branch, they must uncheck the "Allow edits and access to secrets by maintainers" box explicitly.
543
544> [!WARNING]
545> Committers: Branches created via `gh pr checkout` can't be pushed with `--force-with-lease`, so do a sanity check before pushing.
546
547## Code conventions
548[code-conventions]: #code-conventions
549
550### Release notes
551
552If you removed packages or made some major NixOS changes, write about it in the next release notes in [`nixos/doc/manual/release-notes`](./nixos/doc/manual/release-notes).
553
554### File naming and organisation
555
556Names of files and directories should be in lowercase, with dashes between words — kebab case, not camel case.
557For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.
558
559### Formatting
560
561CI [enforces](./.github/workflows/lint.yml) all Nix files to be formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).
562
563You can ensure this locally using either of these commands:
564```
565nix-shell --run treefmt
566nix develop --command treefmt
567nix fmt
568```
569
570If you're starting your editor in `nix-shell` or `nix develop`, you can also set it up to automatically run `treefmt` on save.
571
572If 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).
573
574### Syntax
575
576- Set up [editorconfig](https://editorconfig.org) for your editor, such that [the settings](./.editorconfig) are automatically applied.
577
578- Use `lowerCamelCase` for variable names, not `UpperCamelCase`.
579  Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).
580
581- Functions should list their expected arguments as precisely as possible.
582  That is, write
583
584  ```nix
585  {
586    stdenv,
587    fetchurl,
588    perl,
589  }:
590  <...>
591  ```
592
593  instead of
594
595  ```nix
596  args: with args; <...>
597  ```
598
599  or
600
601  ```nix
602  {
603    stdenv,
604    fetchurl,
605    perl,
606    ...
607  }:
608  <...>
609  ```
610
611  For functions that are truly generic in the number of arguments, but have some required arguments, you should write them using an `@`-pattern:
612
613  ```nix
614  {
615    stdenv,
616    doCoverageAnalysis ? false,
617    ...
618  }@args:
619
620  stdenv.mkDerivation (args // { foo = if doCoverageAnalysis then "bla" else ""; })
621  ```
622
623  instead of
624
625  ```nix
626  args:
627
628  args.stdenv.mkDerivation (
629    args
630    // {
631      foo = if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "";
632    }
633  )
634  ```
635
636- Unnecessary string conversions should be avoided.
637  Do
638
639  ```nix
640  { rev = version; }
641  ```
642
643  instead of
644
645  ```nix
646  { rev = "${version}"; }
647  ```
648
649- Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
650
651  ```nix
652  { buildInputs = lib.optional stdenv.hostPlatform.isDarwin iconv; }
653  ```
654
655  instead of
656
657  ```nix
658  { buildInputs = if stdenv.hostPlatform.isDarwin then [ iconv ] else null; }
659  ```
660
661  As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.
662  If this is done a follow up pull request _should_ be created to change the code to `lib.optional(s)`.
663
664- Any style choices not covered here but that can be expressed as general rules should be left at the discretion of the authors of changes and _not_ commented in reviews.
665  The purpose of this is:
666   - to avoid churn as contributors with different style preferences undo each other's changes,
667   - to ensure that style rules are written down and consistent (and can thus be followed when authoring changes, reducing review cycles),
668   - and to encourage reviews to focus on more impactful considerations.
669
670# Practical contributing advice
671
672To contribute effectively and efficiently, you need to be aware of how the process generally works.
673This section aims to document the process as we live it in Nixpkgs to set the right expectations and give practical tips on how to work with it.
674
675## I opened a PR, how do I get it merged?
676[i-opened-a-pr-how-do-i-get-it-merged]:#i-opened-a-pr-how-do-i-get-it-merged
677
678In order for your PR to be merged, a committer needs to review and merge it.
679Because committers are mostly independent, unpaid volunteers, this can take time.
680It is entirely normal for your PR to sit around without any feedback for days, weeks or sometimes even months.
681We strive to avoid this, but the reality is that it happens frequently.
682Even when you get feedback, follow-ups may take just as long.
683Don't be intimidated and kindly ask for feedback again every so often.
684If your change is good, it will eventually be merged.
685
686You can often speed up the process by understanding the committer's perspective and preparing your PR with reviewing in mind.
687
688### The committer's perspective
689
690PRs have varying quality and even the best people make mistakes.
691Committers need to assess whether a PR's changes are good or not.
692To merge, at least one committer has to be confident about its quality.
693
694Committers typically assess three aspects:
695
6961. Whether the change's intention is necessary and desirable.
6972. Whether the code quality of your changes is good.
6983. Whether the produced artifacts are good.
699
700To get your PR merged quickly and smoothly, you should help convince committers in these aspects.
701
702### How to help committers assess your PR
703
704It's best to explain *why* you've made your change, because guessing the intention is not always possible.
705This does not apply to trivial changes like version updates, because the intention is obvious.
706For more nuanced changes or even major version upgrades, it helps if you explain the background behind your change.
707For example, if you're adding a package, explain what it is and why it should be in Nixpkgs.
708This goes hand in hand with [Writing good commit messages](#writing-good-commit-messages).
709
710To show the quality of your code, you should focus on making it *reviewable*.
711First, take a look at your code changes yourself and try to put yourself into the shoes of someone who didn't just write that code.
712Would you immediately know what the code does or why it is needed by glancing at it?
713If not, reviewers will notice this and will ask you to clarify the code by refactoring it and/or adding code comments.
714Doing this preemptively can save a lot of time.
715Doing multiple unrelated changes in a single commit can become hard to review quickly.
716Thus, consider multiple atomic commits to tell the story of your change.
717There is a balance to strike however: over-fragmentation causes friction.
718
719The artifacts are the hardest to assess because PRs touch all sorts of components: applications, libraries, NixOS modules, editor plugins and many other things.
720Any individual committer can only really assess components that they themselves know how to use.
721Yet, they must still be convinced somehow.
722There isn't a good generic solution to this but there are some ways to ease it:
723
724- Provide smoke tests that can be run without much research or setup.
725
726  Committers usually don't have the time or interest to learn how your component works and how they could test its functionality.
727  Try to provide a quick guide on how to use it in a meaningful way or a ready-made command that demonstrates that it works as expected.
728  The committer can use this to convince themselves that your change is good.
729  If it can be automated, you could even turn this into an automated NixOS test which reviewers could simply run.
730
731- Invite other users of the component to try it out and report their findings.
732
733  Seeing other users testing the changes and having it work for them can convince committers, too.
734
735- Describe what you have done to test your PR.
736
737  It also helps, if you can additionally show that you have done sufficient quality assurance on your changes.
738
739- Become a maintainer of the component.
740
741  Listed maintainers generally receive more trust when it comes to changes to their maintained components.
742
743Even if you adhere to all of these recommendations, it is still quite possible for your PR to be forgotten or abandoned by any given committer.
744Please remain mindful of them doing this work on their own volition and unpaid in their free time and therefore [owing you nothing](https://mikemcquaid.com/open-source-maintainers-owe-you-nothing/).
745Causing a stink in such a situation is a surefire way to get any other potential committer to not want to look at your PR either.
746Ask them nicely whether they still intend to review your PR and find yourself another committer to look at your PR if not.
747
748### How can I get a committer to look at my PR?
749
750- Improve skimmability: use a simple descriptive PR title outlining _what_ is done and _why_.
751  Details go in commit messages.
752- Improve discoverability: apply all relevant labels, tick all relevant PR body checkboxes.
753- Wait.
754  Reviewers frequently browse open PRs and may happen to run across yours and take a look.
755- Get non-committers to review/approve.
756  Many committers filter open PRs for low-hanging fruit that have already been reviewed.
757- [@-mention](https://github.blog/news-insights/mention-somebody-they-re-notified/) someone and ask them nicely.
758- Post in one of the channels made for this purpose if there has been no activity for at least one week:
759  - The current "PRs ready for review" or "PRs already reviewed" threads in the [NixOS Discourse](https://discourse.nixos.org/c/dev/14).
760  - The [Nixpkgs Review Requests Matrix room](https://matrix.to/#/#review-requests:nixos.org).
761  - Similar threads/rooms in unofficial NixOS spaces, such as Discord.
762
763### CI failed or got stuck on my PR, what do I do?
764
765First, ensure that the failure is actually related to your change.
766Sometimes, the CI system simply has a hiccup or the check was broken by someone else before.
767Read through the error message; it's usually quite easy to tell whether it is caused by changes to the component you touched.
768If it is indeed caused by your change, try to fix it.
769Don't be afraid of asking for advice if you're uncertain how to do that, others might have fixed such issues already and can help you out.
770Your PR will not be merged while CI is still failing.
771
772ofborg builds can often get stuck, particularly in PRs targeting `staging` and in builders for the Darwin platform.
773Reviewers will know how to handle them or when to ignore them.
774Don't worry about it.
775However, if there is a build failure and it was caused by your change, you need to investigate it.
776If ofborg reveals the build to be broken on a platform that you don't have access to, consider setting your package's `meta.broken`, `meta.badPlatforms` or `meta.platforms` accordingly.
777
778When in any doubt, please ask via comments or through one of the help channels.
779
780## I received a review, how do I get it over the finish line?
781
782Most likely, a reviewer wants you to change a few things or requires further input.
783
784A reviewer may have taken a look at the code and it looked good to them ("Diff LGTM"), but they still need to be convinced of the artifact's quality.
785They might also be waiting on input from other users or maintainers on whether the intention and direction of your PR makes sense.
786If you know of people who could help clarify any of this, please bring the PR to their attention.
787The current state of the PR is frequently not clearly communicated, so please don't hesitate to ask about it if it's unclear to you.
788
789It's also possible for the reviewer to not be convinced that your PR is necessary or that the method you've chosen is the right one.
790
791Please explain your intentions and reasoning to the committer in such a case.
792There may be constraints you had to work with which they're not aware of or qualities of your approach that they didn't immediately notice.
793If these weren't clear to the reviewer, that's a good sign you should explain them in your commit message or code comments!
794
795There are some further pitfalls and realities to be aware of:
796
797### Aim to reduce cycles
798
799Be prepared for it to take a while for the reviewer to get back to you after you respond.
800This is simply the reality of projects at the scale of Nixpkgs.
801As such, make sure to respond to _all_ feedback at once.
802It wastes everyone's time to wait for a couple of days just to have the reviewer need to remind you to address something they asked for.
803
804### A reviewer requested a bunch of insubstantial changes
805
806The people involved in Nixpkgs care about code quality.
807Once in Nixpkgs, the code needs to be maintained for many years to come.
808Therefore, you will likely be asked to do something different or adhere to a standard.
809
810Sometimes however, they also care a bit too much and may ask you to adhere to a personal preference of theirs.
811It's not always easy to tell whether or not the requested changes must be addressed.
812Sometimes, another reviewer may even have a _conflicting_ opinion on some points.
813
814It is convention to mark review comments that are not required to merge as nitpicks, but this is not always followed.
815As the author, you should still take a look at these, as they will often reveal best practices and unwritten rules.
816Those usually have good reasons behind them and you may want to pick them up as well.
817
818Please keep in mind that reviewers always mean well.
819Their intent is not to denounce your code, they want your code to be as good as it can be.
820Through their experience, they may also take notice of a seemingly insignificant issue that has caused problems before.
821
822Sometimes however, they can also get a bit carried away and become too perfectionistic.
823If you feel some of the requests are unreasonable, out of scope, or merely a matter of personal preference, try to nicely ask the reviewers whether these requests are *critical* to the PR's success.
824
825While we do have a set of [official standards for the Nix community](https://github.com/NixOS/rfcs), we don't have standards for everything and there are often multiple valid ways to achieve the same goal.
826Unless there are standards forbidding the patterns used in your code or there are serious technical, maintainability or readability issues with your code, you can disregard these requests.
827Please communicate this clearly though; a simple "I prefer it this way and see no major issue maintaining it" can save a lot of arguing.
828
829If you are unsure about some change requests, please ask reviewers *why* they requested them.
830This will usually reveal how important they deem it to be and will help educate you about standards, best practices, unwritten rules as well as preferences people have and why.
831
832Some committers have stronger opinions on some things and may not want to merge your PR if you don't follow their requests.
833It is totally fine to get yourself a second or third opinion in such a case.
834
835### Committers work on a push-basis
836
837It's possible for you to get a review but nothing happens afterwards, even if you respond to review comments.
838A committer not following up on your PR does not necessarily mean they're disinterested, they may have simply had other circumstances preventing them from doing so.
839
840Committers typically handle many PRs at the same time and it is not realistic for them to keep up with all of them immediately.
841If someone approved and didn't merge a few days later, they most likely just forgot.
842
843Please see it as your responsibility to actively remind reviewers of your open PRs.
844
845The easiest way to do so is to notify them via GitHub.
846Github notifies people involved, whenever you add a comment or push to your PR or re-request their review.
847Doing any of that will get their attention again.
848Everyone deserves proper attention, and yes, that includes you!
849However, please be mindful that committers can sadly not always give everyone the attention they deserve.
850
851It may very well be the case that you have to do this every time you need the committer to follow up upon your PR.
852Again, this is a community project so please be mindful of people's circumstances here; be nice when requesting reviews again.
853
854It may also be the case that the committer has lost interest or isn't familiar enough with the component you're touching to be comfortable to merge.
855They will likely not immediately state that fact, so please ask for clarification and don't hesitate to find yourself another committer to take a look.
856
857### Nothing helped
858
859If you followed these guidelines but still got no results or if you feel that you have been wronged, please explicitly reach out to the greater community.
860
861The [NixOS Discourse](https://discourse.nixos.org) is a great place to do this, as it has historically been the asynchronous medium with the greatest concentration of committers and other people who are involved in Nixpkgs.
862There is a dedicated discourse thread [PRs in distress](https://discourse.nixos.org/t/prs-in-distress/3604) where you can link your PR, if everything else fails.
863The [Nixpkgs / NixOS contributions Matrix channel](https://matrix.to/#/#dev:nixos.org) is the best synchronous channel with the same qualities.
864
865Please reserve these for cases where you've made a serious effort in trying to get the attention of multiple active committers and provided realistic means for them to assess your PR's quality.
866As mentioned previously, it is unfortunately perfectly normal for a PR to sit around for weeks.
867
868Please don't blow up situations where progress is happening but is merely not going fast enough for your tastes.
869Honking in a traffic jam will not make you go any faster.