commit 86f14e461ef18bf5c0dbc63f46fdc5d13d183628 · pyrox.dev/nixpkgs

+272 -1

CONTRIBUTING-new.md

···

       27
       27
        
       

     

       28
       28
        
           The old config generation system used impure shell scripts and could break in specific circumstances (see #1234).

     

       29
       29
        
       

     

       30
       30
       +
       ### Making patches {#submitting-changes-making-patches}

     

       31
       31
       +
       

     

       32
       32
       +
       - Read [Manual (How to write packages for Nix)](https://nixos.org/nixpkgs/manual/).

     

       33
       33
       +
       

     

       34
       34
       +
       - Fork [the Nixpkgs repository](https://github.com/nixos/nixpkgs/) on GitHub.

     

       35
       35
       +
       

     

       36
       36
       +
       - Create a branch for your future fix.

     

       37
       37
       +
       

     

       38
       38
       +
         - You can make branch from a commit of your local `nixos-version`. That will help you to avoid additional local compilations. Because you will receive packages from binary cache. For example

     

       39
       39
       +
       

     

       40
       40
       +
           ```ShellSession

     

       41
       41
       +
           $ nixos-version --hash

     

       42
       42
       +
           0998212

     

       43
       43
       +
           $ git checkout 0998212

     

       44
       44
       +
           $ git checkout -b 'fix/pkg-name-update'

     

       45
       45
       +
           ```

     

       46
       46
       +
       

     

       47
       47
       +
         - Please avoid working directly on the `master` branch.

     

       48
       48
       +
       

     

       49
       49
       +
       - Make commits of logical units.

     

       50
       50
       +
       

     

       51
       51
       +
       - If you removed pkgs or made some major NixOS changes, write about it in the release notes for the next stable release. For example `nixos/doc/manual/release-notes/rl-2003.xml`.

     

       52
       52
       +
       

     

       53
       53
       +
       - Check for unnecessary whitespace with `git diff --check` before committing.

     

       54
       54
       +
       

     

       55
       55
       +
       - Format the commit in a following way:

     

       56
       56
       +
       

     

       57
       57
       +
         ```

     

       58
       58
       +
         (pkg-name | nixos/<module>): (from -> to | init at version | refactor | etc)

     

       59
       59
       +
         Additional information.

     

       60
       60
       +
         ```

     

       61
       61
       +
       

     

       62
       62
       +
         - Examples:

     

       63
       63
       +
           - `nginx: init at 2.0.1`

     

       64
       64
       +
           - `firefox: 54.0.1 -> 55.0`

     

       65
       65
       +
           - `nixos/hydra: add bazBaz option`

     

       66
       66
       +
           - `nixos/nginx: refactor config generation`

     

       67
       67
       +
       

     

       68
       68
       +
       - Test your changes. If you work with

     

       69
       69
       +
       

     

       70
       70
       +
         - nixpkgs:

     

       71
       71
       +
       

     

       72
       72
       +
           - update pkg

     

       73
       73
       +
             - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`

     

       74
       74
       +
           - add pkg

     

       75
       75
       +
             - Make sure it’s in `pkgs/top-level/all-packages.nix`

     

       76
       76
       +
             - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`

     

       77
       77
       +
           - _If you don’t want to install pkg in you profile_.

     

       78
       78
       +
             - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.

     

       79
       79
       +
           - If you installed your package with `nix-env`, you can run `nix-env -e pkg-name` where `pkg-name` is as reported by `nix-env -q` to uninstall it from your system.

     

       80
       80
       +
       

     

       81
       81
       +
         - NixOS and its modules:

     

       82
       82
       +
           - 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`.

     

       83
       83
       +
       

     

       84
       84
       +
       - If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`.

     

       85
       85
       +
       

     

       86
       86
       +
       - [Rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) your branch against current `master`.

     

       30
       87
        
       

     

       31
       88
        
       ### Writing good commit messages

     

       32
       89
        
       

     
···

       39
       96
        
       Useful git commands that can help a lot with this are `git commit --patch --amend` and `git rebase --interactive`. For more details consult the git man pages or online resources like [git-rebase.io](https://git-rebase.io/) or [The Pro Git Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).

     

       40
       97
        
       

     

       41
       98
        
       ### (Creating a pull request)

     

       99
       99
       +
       

     

       100
       100
       +
       - Push your changes to your fork of nixpkgs.

     

       101
       101
       +
       - Create the pull request

     

       102
       102
       +
       - Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#submitting-changes).

     

       42
       103
        
       

     

       43
       104
        
       When pull requests are made, our tooling automation bot,

     

       44
       105
        
       [OfBorg](https://github.com/NixOS/ofborg) will perform various checks

     

       45
       106
        
       to help ensure expression quality.

     

       46
       107
        
       

     

       108
       108
       +
       #### Pull Request Template {#submitting-changes-pull-request-template}

     

       109
       109
       +
       

     

       110
       110
       +
       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.

     

       111
       111
       +
       

     

       112
       112
       +
       When a PR is created, it will be pre-populated with some checkboxes detailed below:

     

       113
       113
       +
       

     

       114
       114
       +
       ##### Tested using sandboxing {#submitting-changes-tested-with-sandbox}

     

       115
       115
       +
       

     

       116
       116
       +
       When sandbox builds are enabled, Nix will setup an isolated environment for each build process. It is used to remove further hidden dependencies set by the build environment to improve reproducibility. This includes access to the network during the build outside of `fetch*` functions and files outside the Nix store. Depending on the operating system access to other resources are blocked as well (ex. inter process communication is isolated on Linux); see [sandbox](https://nixos.org/nix/manual/#conf-sandbox) in Nix manual for details.

     

       117
       117
       +
       

     

       118
       118
       +
       Sandboxing is not enabled by default in Nix due to a small performance hit on each build. In pull requests for [nixpkgs](https://github.com/NixOS/nixpkgs/) people are asked to test builds with sandboxing enabled (see `Tested using sandboxing` in the pull request template) because in<https://nixos.org/hydra/> sandboxing is also used.

     

       119
       119
       +
       

     

       120
       120
       +
       Depending if you use NixOS or other platforms you can use one of the following methods to enable sandboxing **before** building the package:

     

       121
       121
       +
       

     

       122
       122
       +
       - **Globally enable sandboxing on NixOS**: add the following to `configuration.nix`

     

       123
       123
       +
       

     

       124
       124
       +
         ```nix

     

       125
       125
       +
         nix.useSandbox = true;

     

       126
       126
       +
         ```

     

       127
       127
       +
       

     

       128
       128
       +
       - **Globally enable sandboxing on non-NixOS platforms**: add the following to: `/etc/nix/nix.conf`

     

       129
       129
       +
       

     

       130
       130
       +
         ```ini

     

       131
       131
       +
         sandbox = true

     

       132
       132
       +
         ```

     

       133
       133
       +
       

     

       134
       134
       +
       ##### Built on platform(s) {#submitting-changes-platform-diversity}

     

       135
       135
       +
       

     

       136
       136
       +
       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.

     

       137
       137
       +
       

     

       138
       138
       +
       ##### Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests) {#submitting-changes-nixos-tests}

     

       139
       139
       +
       

     

       140
       140
       +
       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).

     

       141
       141
       +
       

     

       142
       142
       +
       ##### Tested compilation of all pkgs that depend on this change using `nixpkgs-review` {#submitting-changes-tested-compilation}

     

       143
       143
       +
       

     

       144
       144
       +
       If you are updating a package’s version, 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.

     

       145
       145
       +
       

     

       146
       146
       +
       Review changes from pull request number 12345:

     

       147
       147
       +
       

     

       148
       148
       +
       ```ShellSession

     

       149
       149
       +
       nix-shell -p nixpkgs-review --run "nixpkgs-review pr 12345"

     

       150
       150
       +
       ```

     

       151
       151
       +
       

     

       152
       152
       +
       Alternatively, with flakes (and analogously for the other commands below):

     

       153
       153
       +
       

     

       154
       154
       +
       ```ShellSession

     

       155
       155
       +
       nix run nixpkgs#nixpkgs-review -- pr 12345

     

       156
       156
       +
       ```

     

       157
       157
       +
       

     

       158
       158
       +
       Review uncommitted changes:

     

       159
       159
       +
       

     

       160
       160
       +
       ```ShellSession

     

       161
       161
       +
       nix-shell -p nixpkgs-review --run "nixpkgs-review wip"

     

       162
       162
       +
       ```

     

       163
       163
       +
       

     

       164
       164
       +
       Review changes from last commit:

     

       165
       165
       +
       

     

       166
       166
       +
       ```ShellSession

     

       167
       167
       +
       nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"

     

       168
       168
       +
       ```

     

       169
       169
       +
       

     

       170
       170
       +
       ##### Tested execution of all binary files (usually in `./result/bin/`) {#submitting-changes-tested-execution}

     

       171
       171
       +
       

     

       172
       172
       +
       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.

     

       173
       173
       +
       

     

       174
       174
       +
       ##### Meets Nixpkgs contribution standards {#submitting-changes-contribution-standards}

     

       175
       175
       +
       

     

       176
       176
       +
       The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing 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.

     

       177
       177
       +
       

     

       47
       178
        
       #### Rebasing between branches (i.e. from master to staging)

     

       48
       179
        
       

     

       49
       180
        
       From time to time, changes between branches must be rebased, for example, if the

     
···

       144
       275
        
       - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)

     

       145
       276
        
       - Security critical applications (E.g. `firefox`)

     

       146
       277
        
       

     

       278
       278
       +
       ### Hotfixing pull requests {#submitting-changes-hotfixing-pull-requests}

     

       279
       279
       +
       

     

       280
       280
       +
       - Make the appropriate changes in you branch.

     

       281
       281
       +
       - Don’t create additional commits, do

     

       282
       282
       +
         - `git rebase -i`

     

       283
       283
       +
         - `git push --force` to your branch.

     

       284
       284
       +
       

     

       147
       285
        
       ## Reviewing contributions {#chap-reviewing-contributions}

     

       148
       286
        
       

     

       149
       287
        
       ::: {.warning}

     
···

       193
       331
        
       

     

       194
       332
        
       In a case a contributor definitively leaves the Nix community, they should create an issue or post on [Discourse](https://discourse.nixos.org) with references of packages and modules they maintain so the maintainership can be taken over by other contributors.

     

       195
       333
        
       

     

       196
       196
       -
       ## (Flow of changes)

     

       334
       334
       +
       ## (Flow of changes) | Commit policy {#submitting-changes-commit-policy}

     

       197
       335
        
       

     

       198
       336
        
       Most contributions are based on and merged into these branches:

     

       199
       337
        
       

     
···

       204
       342
        
         and security fixes with a big impact on Hydra builds should be

     

       205
       343
        
         contributed to this branch. This branch is merged into master when

     

       206
       344
        
         deemed of sufficiently high quality

     

       345
       345
       +
       

     

       346
       346
       +
       - Commits must be sufficiently tested before being merged, both for the master and staging branches.

     

       347
       347
       +
       - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested.

     

       348
       348
       +
       - 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.

     

       349
       349
       +
       

     

       350
       350
       +
       ### Branches {#submitting-changes-branches}

     

       351
       351
       +
       

     

       352
       352
       +
       The `nixpkgs` repository has three major branches:

     

       353
       353
       +
       - `master`

     

       354
       354
       +
       - `staging`

     

       355
       355
       +
       - `staging-next`

     

       356
       356
       +
       

     

       357
       357
       +
       The most important distinction between them is that `staging`

     

       358
       358
       +
       (colored red in the diagram below) can receive commits which cause

     

       359
       359
       +
       a mass-rebuild (for example, anything that changes the `drvPath` of

     

       360
       360
       +
       `stdenv`).  The other two branches `staging-next` and `master`

     

       361
       361
       +
       (colored green in the diagram below) can *not* receive commits which

     

       362
       362
       +
       cause a mass-rebuild.

     

       363
       363
       +
       

     

       364
       364
       +
       Arcs between the branches show possible merges into these branches,

     

       365
       365
       +
       either from other branches or from independently submitted PRs.  The

     

       366
       366
       +
       colors of these edges likewise show whether or not they could

     

       367
       367
       +
       trigger a mass rebuild (red) or must not trigger a mass rebuild

     

       368
       368
       +
       (green).

     

       369
       369
       +
       

     

       370
       370
       +
       Hydra runs automatic builds for the green branches.

     

       371
       371
       +
       

     

       372
       372
       +
       Notice that the automatic merges are all green arrows.  This is by

     

       373
       373
       +
       design.  Any merge which might cause a mass rebuild on a branch

     

       374
       374
       +
       which has automatic builds (`staging-next`, `master`) will be a

     

       375
       375
       +
       manual merge to make sure it is good use of compute power.

     

       376
       376
       +
       

     

       377
       377
       +
       Nixpkgs has two branches so that there is one branch (`staging`)

     

       378
       378
       +
       which accepts mass-rebuilding commits, and one fast-rebuilding

     

       379
       379
       +
       branch which accepts independent PRs (`master`).  The `staging-next`

     

       380
       380
       +
       branch allows the Hydra operators to batch groups of commits to

     

       381
       381
       +
       `staging` to be built.  By keeping the `staging-next` branch

     

       382
       382
       +
       separate from `staging`, this batching does not block

     

       383
       383
       +
       developers from merging changes into `staging`.

     

       384
       384
       +
       

     

       385
       385
       +
       ```{.graphviz caption="Staging workflow"}

     

       386
       386
       +
       digraph {

     

       387
       387
       +
           master [color="green" fontcolor=green]

     

       388
       388
       +
           "staging-next" [color="green" fontcolor=green]

     

       389
       389
       +
           staging [color="red" fontcolor=red]

     

       390
       390
       +
       

     

       391
       391
       +
           "small changes" [fontcolor=green shape=none]

     

       392
       392
       +
           "small changes" -> master [color=green]

     

       393
       393
       +
       

     

       394
       394
       +
           "mass-rebuilds and other large changes" [fontcolor=red shape=none]

     

       395
       395
       +
           "mass-rebuilds and other large changes" -> staging [color=red]

     

       396
       396
       +
       

     

       397
       397
       +
           "critical security fixes" [fontcolor=green shape=none]

     

       398
       398
       +
           "critical security fixes" -> master [color=green]

     

       399
       399
       +
       

     

       400
       400
       +
           "staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]

     

       401
       401
       +
           "staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]

     

       402
       402
       +
       

     

       403
       403
       +
           "staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]

     

       404
       404
       +
           "staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]

     

       405
       405
       +
       

     

       406
       406
       +
           master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       407
       407
       +
           "staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       408
       408
       +
       }

     

       409
       409
       +
       ```

     

       410
       410
       +
       

     

       411
       411
       +
       [This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above.  The red arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.

     

       412
       412
       +
       

     

       413
       413
       +
       

     

       414
       414
       +
       #### Master branch {#submitting-changes-master-branch}

     

       415
       415
       +
       

     

       416
       416
       +
       The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.

     

       417
       417
       +
       

     

       418
       418
       +
       #### Staging branch {#submitting-changes-staging-branch}

     

       419
       419
       +
       

     

       420
       420
       +
       The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.

     

       421
       421
       +
       

     

       422
       422
       +
       During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       423
       423
       +
       

     

       424
       424
       +
       #### Staging-next branch {#submitting-changes-staging-next-branch}

     

       425
       425
       +
       

     

       426
       426
       +
       The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.

     

       427
       427
       +
       

     

       428
       428
       +
       If the branch is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days and then merge into master.

     

       429
       429
       +
       

     

       430
       430
       +
       During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       431
       431
       +
       

     

       432
       432
       +
       #### Stable release branches {#submitting-changes-stable-release-branches}

     

       433
       433
       +
       

     

       434
       434
       +
       The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.

     

       435
       435
       +
       

     

       436
       436
       +
       Example branch names: `release-21.11`, `staging-21.11`, `staging-next-21.11`.

     

       437
       437
       +
       

     

       438
       438
       +
       Most changes added to the stable release branches are cherry-picked (“backported”) from the `master` and staging branches.

     

       439
       439
       +
       

     

       440
       440
       +
       #### Automatically backporting a Pull Request {#submitting-changes-stable-release-branches-automatic-backports}

     

       441
       441
       +
       

     

       442
       442
       +
       Assign label `backport <branch>` (e.g. `backport release-21.11`) to the PR and a backport PR is automatically created after the PR is merged.

     

       443
       443
       +
       

     

       444
       444
       +
       #### Manually backporting changes {#submitting-changes-stable-release-branches-manual-backports}

     

       445
       445
       +
       

     

       446
       446
       +
       Cherry-pick changes via `git cherry-pick -x <original commit>` so that the original commit id is included in the commit message.

     

       447
       447
       +
       

     

       448
       448
       +
       Add a reason for the backport when it is not obvious from the original commit message. You can do this by cherry picking with `git cherry-pick -xe <original commit>`, which allows editing the commit message. This is not needed for minor version updates that include security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.

     

       449
       449
       +
       

     

       450
       450
       +
       Here is an example of a cherry-picked commit message with good reason description:

     

       451
       451
       +
       

     

       452
       452
       +
       ```

     

       453
       453
       +
       zfs: Keep trying root import until it works

     

       454
       454
       +
       

     

       455
       455
       +
       Works around #11003.

     

       456
       456
       +
       

     

       457
       457
       +
       (cherry picked from commit 98b213a11041af39b39473906b595290e2a4e2f9)

     

       458
       458
       +
       

     

       459
       459
       +
       Reason: several people cannot boot with ZFS on NVMe

     

       460
       460
       +
       ```

     

       461
       461
       +
       

     

       462
       462
       +
       Other examples of reasons are:

     

       463
       463
       +
       

     

       464
       464
       +
       - Previously the build would fail due to, e.g., `getaddrinfo` not being defined

     

       465
       465
       +
       - The previous download links were all broken

     

       466
       466
       +
       - Crash when starting on some X11 systems

     

       467
       467
       +
       

     

       468
       468
       +
       #### Acceptable backport criteria {#acceptable-backport-criteria}

     

       469
       469
       +
       

     

       470
       470
       +
       The stable branch does have some changes which cannot be backported. Most notable are breaking changes. The desire is to have stable users be uninterrupted when updating packages.

     

       471
       471
       +
       

     

       472
       472
       +
       However, many changes are able to be backported, including:

     

       473
       473
       +
       - New Packages / Modules

     

       474
       474
       +
       - Security / Patch updates

     

       475
       475
       +
       - Version updates which include new functionality (but no breaking changes)

     

       476
       476
       +
       - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)

     

       477
       477
       +
       - Security critical applications (E.g. `firefox`)

     

       207
       478
        
       

     

       208
       479
        
       ## Coding conventions {#chap-conventions}

     

       209
       480

+22 -278

doc/contributing/submitting-changes.chapter.md

···

       1
       1
        
       # Submitting changes {#chap-submitting-changes}

     

       2
       2
        
       

     

       3
       3
       -
       ## Making patches {#submitting-changes-making-patches}

     

       4
       4
       -
       

     

       5
       5
       -
       - Read [Manual (How to write packages for Nix)](https://nixos.org/nixpkgs/manual/).

     

       6
       6
       -
       

     

       7
       7
       -
       - Fork [the Nixpkgs repository](https://github.com/nixos/nixpkgs/) on GitHub.

     

       8
       8
       -
       

     

       9
       9
       -
       - Create a branch for your future fix.

     

       10
       10
       -
       

     

       11
       11
       -
         - You can make branch from a commit of your local `nixos-version`. That will help you to avoid additional local compilations. Because you will receive packages from binary cache. For example

     

       12
       12
       -
       

     

       13
       13
       -
           ```ShellSession

     

       14
       14
       -
           $ nixos-version --hash

     

       15
       15
       -
           0998212

     

       16
       16
       -
           $ git checkout 0998212

     

       17
       17
       -
           $ git checkout -b 'fix/pkg-name-update'

     

       18
       18
       -
           ```

     

       19
       19
       -
       

     

       20
       20
       -
         - Please avoid working directly on the `master` branch.

     

       21
       21
       -
       

     

       22
       22
       -
       - Make commits of logical units.

     

       23
       23
       -
       

     

       24
       24
       -
       - If you removed pkgs or made some major NixOS changes, write about it in the release notes for the next stable release. For example `nixos/doc/manual/release-notes/rl-2003.xml`.

     

       25
       25
       -
       

     

       26
       26
       -
       - Check for unnecessary whitespace with `git diff --check` before committing.

     

       27
       27
       -
       

     

       28
       28
       -
       - Format the commit in a following way:

     

       29
       29
       -
       

     

       30
       30
       -
         ```

     

       31
       31
       -
         (pkg-name | nixos/<module>): (from -> to | init at version | refactor | etc)

     

       32
       32
       -
         Additional information.

     

       33
       33
       -
         ```

     

       34
       34
       -
       

     

       35
       35
       -
         - Examples:

     

       36
       36
       -
           - `nginx: init at 2.0.1`

     

       37
       37
       -
           - `firefox: 54.0.1 -> 55.0`

     

       38
       38
       -
           - `nixos/hydra: add bazBaz option`

     

       39
       39
       -
           - `nixos/nginx: refactor config generation`

     

       40
       40
       -
       

     

       41
       41
       -
       - Test your changes. If you work with

     

       42
       42
       -
       

     

       43
       43
       -
         - nixpkgs:

     

       44
       44
       -
       

     

       45
       45
       -
           - update pkg

     

       46
       46
       -
             - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`

     

       47
       47
       -
           - add pkg

     

       48
       48
       -
             - Make sure it’s in `pkgs/top-level/all-packages.nix`

     

       49
       49
       -
             - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`

     

       50
       50
       -
           - _If you don’t want to install pkg in you profile_.

     

       51
       51
       -
             - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.

     

       52
       52
       -
           - If you installed your package with `nix-env`, you can run `nix-env -e pkg-name` where `pkg-name` is as reported by `nix-env -q` to uninstall it from your system.

     

       53
       53
       -
       

     

       54
       54
       -
         - NixOS and its modules:

     

       55
       55
       -
           - 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`.

     

       56
       56
       -
       

     

       57
       57
       -
       - If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`.

     

       58
       58
       -
       

     

       59
       59
       -
       - [Rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) your branch against current `master`.

     

       3
       3
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       60
       4
        
       

     

       61
       5
        
       ## Submitting changes {#submitting-changes-submitting-changes}

     

       62
       6
        
       

     

       63
       63
       -
       - Push your changes to your fork of nixpkgs.

     

       64
       64
       -
       - Create the pull request

     

       65
       65
       -
       - Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#submitting-changes).

     

       7
       7
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       66
       8
        
       

     

       67
       9
        
       ## Submitting security fixes {#submitting-changes-submitting-security-fixes}

     

       68
       10
        
       

     

       69
       69
       -
       Security fixes are submitted in the same way as other changes and thus the same guidelines apply.

     

       70
       70
       -
       

     

       71
       71
       -
       - If a new version fixing the vulnerability has been released, update the package;

     

       72
       72
       -
       - If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.

     

       73
       73
       -
         The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:

     

       74
       74
       -
       

     

       75
       75
       -
         ```nix

     

       76
       76
       -
         (fetchpatch {

     

       77
       77
       -
           name = "CVE-2019-11068.patch";

     

       78
       78
       -
           url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";

     

       79
       79
       -
           hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";

     

       80
       80
       -
         })

     

       81
       81
       -
         ```

     

       82
       82
       -
       

     

       83
       83
       -
       If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch.

     

       84
       84
       -
       

     

       85
       85
       -
       Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`.

     

       11
       11
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       86
       12
        
       

     

       87
       13
        
       ## Deprecating/removing packages {#submitting-changes-deprecating-packages}

     

       88
       14
        
       

     

       89
       89
       -
       There is currently no policy when to remove a package.

     

       90
       90
       -
       

     

       91
       91
       -
       Before removing a package, one should try to find a new maintainer or fix smaller issues first.

     

       15
       15
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       92
       16
        
       

     

       93
       17
        
       ### Steps to remove a package from Nixpkgs {#steps-to-remove-a-package-from-nixpkgs}

     

       94
       18
        
       

     

       95
       95
       -
       We use jbidwatcher as an example for a discontinued project here.

     

       96
       96
       -
       

     

       97
       97
       -
       1. Have Nixpkgs checked out locally and up to date.

     

       98
       98
       -
       1. Create a new branch for your change, e.g. `git checkout -b jbidwatcher`

     

       99
       99
       -
       1. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher`

     

       100
       100
       -
       1. Remove the package from the list of all packages (`pkgs/top-level/all-packages.nix`).

     

       101
       101
       -
       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.)

     

       102
       102
       -
       

     

       103
       103
       -
           For example in this case:

     

       104
       104
       -
       

     

       105
       105
       -
           ```

     

       106
       106
       -
           jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15

     

       107
       107
       -
           ```

     

       108
       108
       -
       

     

       109
       109
       -
           The throw message should explain in short why the package was removed for users that still have it installed.

     

       110
       110
       -
       

     

       111
       111
       -
       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.

     

       112
       112
       -
       1. Commit the changes. Explain again why the package was removed. If it was declared discontinued upstream, add a link to the source.

     

       113
       113
       -
       

     

       114
       114
       -
           ```ShellSession

     

       115
       115
       -
           $ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix

     

       116
       116
       -
           $ git commit

     

       117
       117
       -
           ```

     

       118
       118
       -
       

     

       119
       119
       -
           Example commit message:

     

       120
       120
       -
       

     

       121
       121
       -
           ```

     

       122
       122
       -
           jbidwatcher: remove

     

       123
       123
       -
       

     

       124
       124
       -
           project was discontinued in march 2021. the program does not work anymore because ebay changed the login.

     

       125
       125
       -
       

     

       126
       126
       -
           https://web.archive.org/web/20210315205723/http://www.jbidwatcher.com/

     

       127
       127
       -
           ```

     

       128
       128
       -
       

     

       129
       129
       -
       1. Push changes to your GitHub fork with `git push`

     

       130
       130
       -
       1. Create a pull request against Nixpkgs. Mention the package maintainer.

     

       131
       131
       -
       

     

       132
       132
       -
       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)

     

       19
       19
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       133
       20
        
       

     

       134
       21
        
       ## Pull Request Template {#submitting-changes-pull-request-template}

     

       135
       22
        
       

     

       136
       136
       -
       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.

     

       137
       137
       -
       

     

       138
       138
       -
       When a PR is created, it will be pre-populated with some checkboxes detailed below:

     

       23
       23
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       139
       24
        
       

     

       140
       25
        
       ### Tested using sandboxing {#submitting-changes-tested-with-sandbox}

     

       141
       26
        
       

     

       142
       142
       -
       When sandbox builds are enabled, Nix will setup an isolated environment for each build process. It is used to remove further hidden dependencies set by the build environment to improve reproducibility. This includes access to the network during the build outside of `fetch*` functions and files outside the Nix store. Depending on the operating system access to other resources are blocked as well (ex. inter process communication is isolated on Linux); see [sandbox](https://nixos.org/nix/manual/#conf-sandbox) in Nix manual for details.

     

       143
       143
       -
       

     

       144
       144
       -
       Sandboxing is not enabled by default in Nix due to a small performance hit on each build. In pull requests for [nixpkgs](https://github.com/NixOS/nixpkgs/) people are asked to test builds with sandboxing enabled (see `Tested using sandboxing` in the pull request template) because in<https://nixos.org/hydra/> sandboxing is also used.

     

       145
       145
       -
       

     

       146
       146
       -
       Depending if you use NixOS or other platforms you can use one of the following methods to enable sandboxing **before** building the package:

     

       147
       147
       -
       

     

       148
       148
       -
       - **Globally enable sandboxing on NixOS**: add the following to `configuration.nix`

     

       149
       149
       -
       

     

       150
       150
       -
         ```nix

     

       151
       151
       -
         nix.useSandbox = true;

     

       152
       152
       -
         ```

     

       153
       153
       -
       

     

       154
       154
       -
       - **Globally enable sandboxing on non-NixOS platforms**: add the following to: `/etc/nix/nix.conf`

     

       155
       155
       -
       

     

       156
       156
       -
         ```ini

     

       157
       157
       -
         sandbox = true

     

       158
       158
       -
         ```

     

       27
       27
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       159
       28
        
       

     

       160
       29
        
       ### Built on platform(s) {#submitting-changes-platform-diversity}

     

       161
       30
        
       

     

       162
       162
       -
       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.

     

       31
       31
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       163
       32
        
       

     

       164
       33
        
       ### Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests) {#submitting-changes-nixos-tests}

     

       165
       34
        
       

     

       166
       166
       -
       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).

     

       35
       35
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       167
       36
        
       

     

       168
       37
        
       ### Tested compilation of all pkgs that depend on this change using `nixpkgs-review` {#submitting-changes-tested-compilation}

     

       169
       38
        
       

     

       170
       170
       -
       If you are updating a package’s version, 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.

     

       171
       171
       -
       

     

       172
       172
       -
       Review changes from pull request number 12345:

     

       173
       173
       -
       

     

       174
       174
       -
       ```ShellSession

     

       175
       175
       -
       nix-shell -p nixpkgs-review --run "nixpkgs-review pr 12345"

     

       176
       176
       -
       ```

     

       177
       177
       -
       

     

       178
       178
       -
       Alternatively, with flakes (and analogously for the other commands below):

     

       179
       179
       -
       

     

       180
       180
       -
       ```ShellSession

     

       181
       181
       -
       nix run nixpkgs#nixpkgs-review -- pr 12345

     

       182
       182
       -
       ```

     

       183
       183
       -
       

     

       184
       184
       -
       Review uncommitted changes:

     

       185
       185
       -
       

     

       186
       186
       -
       ```ShellSession

     

       187
       187
       -
       nix-shell -p nixpkgs-review --run "nixpkgs-review wip"

     

       188
       188
       -
       ```

     

       189
       189
       -
       

     

       190
       190
       -
       Review changes from last commit:

     

       191
       191
       -
       

     

       192
       192
       -
       ```ShellSession

     

       193
       193
       -
       nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"

     

       194
       194
       -
       ```

     

       39
       39
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       195
       40
        
       

     

       196
       41
        
       ### Tested execution of all binary files (usually in `./result/bin/`) {#submitting-changes-tested-execution}

     

       197
       42
        
       

     

       198
       198
       -
       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.

     

       43
       43
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       199
       44
        
       

     

       200
       45
        
       ### Meets Nixpkgs contribution standards {#submitting-changes-contribution-standards}

     

       201
       46
        
       

     

       202
       202
       -
       The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing 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.

     

       47
       47
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       203
       48
        
       

     

       204
       49
        
       ## Hotfixing pull requests {#submitting-changes-hotfixing-pull-requests}

     

       205
       50
        
       

     

       206
       206
       -
       - Make the appropriate changes in you branch.

     

       207
       207
       -
       - Don’t create additional commits, do

     

       208
       208
       -
         - `git rebase -i`

     

       209
       209
       -
         - `git push --force` to your branch.

     

       51
       51
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       210
       52
        
       

     

       211
       53
        
       ## Commit policy {#submitting-changes-commit-policy}

     

       212
       54
        
       

     

       213
       213
       -
       - Commits must be sufficiently tested before being merged, both for the master and staging branches.

     

       214
       214
       -
       - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested.

     

       215
       215
       -
       - 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.

     

       55
       55
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       216
       56
        
       

     

       217
       57
        
       ### Branches {#submitting-changes-branches}

     

       218
       58
        
       

     

       219
       219
       -
       The `nixpkgs` repository has three major branches:

     

       220
       220
       -
       - `master`

     

       221
       221
       -
       - `staging`

     

       222
       222
       -
       - `staging-next`

     

       223
       223
       -
       

     

       224
       224
       -
       The most important distinction between them is that `staging`

     

       225
       225
       -
       (colored red in the diagram below) can receive commits which cause

     

       226
       226
       -
       a mass-rebuild (for example, anything that changes the `drvPath` of

     

       227
       227
       -
       `stdenv`).  The other two branches `staging-next` and `master`

     

       228
       228
       -
       (colored green in the diagram below) can *not* receive commits which

     

       229
       229
       -
       cause a mass-rebuild.

     

       230
       230
       -
       

     

       231
       231
       -
       Arcs between the branches show possible merges into these branches,

     

       232
       232
       -
       either from other branches or from independently submitted PRs.  The

     

       233
       233
       -
       colors of these edges likewise show whether or not they could

     

       234
       234
       -
       trigger a mass rebuild (red) or must not trigger a mass rebuild

     

       235
       235
       -
       (green).

     

       236
       236
       -
       

     

       237
       237
       -
       Hydra runs automatic builds for the green branches.

     

       238
       238
       -
       

     

       239
       239
       -
       Notice that the automatic merges are all green arrows.  This is by

     

       240
       240
       -
       design.  Any merge which might cause a mass rebuild on a branch

     

       241
       241
       -
       which has automatic builds (`staging-next`, `master`) will be a

     

       242
       242
       -
       manual merge to make sure it is good use of compute power.

     

       243
       243
       -
       

     

       244
       244
       -
       Nixpkgs has two branches so that there is one branch (`staging`)

     

       245
       245
       -
       which accepts mass-rebuilding commits, and one fast-rebuilding

     

       246
       246
       -
       branch which accepts independent PRs (`master`).  The `staging-next`

     

       247
       247
       -
       branch allows the Hydra operators to batch groups of commits to

     

       248
       248
       -
       `staging` to be built.  By keeping the `staging-next` branch

     

       249
       249
       -
       separate from `staging`, this batching does not block

     

       250
       250
       -
       developers from merging changes into `staging`.

     

       251
       251
       -
       

     

       252
       252
       -
       ```{.graphviz caption="Staging workflow"}

     

       253
       253
       -
       digraph {

     

       254
       254
       -
           master [color="green" fontcolor=green]

     

       255
       255
       -
           "staging-next" [color="green" fontcolor=green]

     

       256
       256
       -
           staging [color="red" fontcolor=red]

     

       257
       257
       -
       

     

       258
       258
       -
           "small changes" [fontcolor=green shape=none]

     

       259
       259
       -
           "small changes" -> master [color=green]

     

       260
       260
       -
       

     

       261
       261
       -
           "mass-rebuilds and other large changes" [fontcolor=red shape=none]

     

       262
       262
       -
           "mass-rebuilds and other large changes" -> staging [color=red]

     

       263
       263
       -
       

     

       264
       264
       -
           "critical security fixes" [fontcolor=green shape=none]

     

       265
       265
       -
           "critical security fixes" -> master [color=green]

     

       266
       266
       -
       

     

       267
       267
       -
           "staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]

     

       268
       268
       -
           "staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]

     

       269
       269
       -
       

     

       270
       270
       -
           "staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]

     

       271
       271
       -
           "staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]

     

       272
       272
       -
       

     

       273
       273
       -
           master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       274
       274
       -
           "staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       275
       275
       -
       }

     

       276
       276
       -
       ```

     

       277
       277
       -
       

     

       278
       278
       -
       [This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above.  The red arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.

     

       279
       279
       -
       

     

       59
       59
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       280
       60
        
       

     

       281
       61
        
       #### Master branch {#submitting-changes-master-branch}

     

       282
       62
        
       

     

       283
       283
       -
       The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.

     

       63
       63
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       284
       64
        
       

     

       285
       65
        
       #### Staging branch {#submitting-changes-staging-branch}

     

       286
       66
        
       

     

       287
       287
       -
       The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.

     

       288
       288
       -
       

     

       289
       289
       -
       During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       67
       67
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       290
       68
        
       

     

       291
       69
        
       #### Staging-next branch {#submitting-changes-staging-next-branch}

     

       292
       70
        
       

     

       293
       293
       -
       The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.

     

       294
       294
       -
       

     

       295
       295
       -
       If the branch is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days and then merge into master.

     

       296
       296
       -
       

     

       297
       297
       -
       During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       71
       71
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       298
       72
        
       

     

       299
       73
        
       #### Stable release branches {#submitting-changes-stable-release-branches}

     

       300
       74
        
       

     

       301
       301
       -
       The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.

     

       302
       302
       -
       

     

       303
       303
       -
       Example branch names: `release-21.11`, `staging-21.11`, `staging-next-21.11`.

     

       304
       304
       -
       

     

       305
       305
       -
       Most changes added to the stable release branches are cherry-picked (“backported”) from the `master` and staging branches.

     

       75
       75
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       306
       76
        
       

     

       307
       77
        
       #### Automatically backporting a Pull Request {#submitting-changes-stable-release-branches-automatic-backports}

     

       308
       78
        
       

     

       309
       309
       -
       Assign label `backport <branch>` (e.g. `backport release-21.11`) to the PR and a backport PR is automatically created after the PR is merged.

     

       79
       79
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       310
       80
        
       

     

       311
       81
        
       #### Manually backporting changes {#submitting-changes-stable-release-branches-manual-backports}

     

       312
       82
        
       

     

       313
       313
       -
       Cherry-pick changes via `git cherry-pick -x <original commit>` so that the original commit id is included in the commit message.

     

       314
       314
       -
       

     

       315
       315
       -
       Add a reason for the backport when it is not obvious from the original commit message. You can do this by cherry picking with `git cherry-pick -xe <original commit>`, which allows editing the commit message. This is not needed for minor version updates that include security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.

     

       316
       316
       -
       

     

       317
       317
       -
       Here is an example of a cherry-picked commit message with good reason description:

     

       318
       318
       -
       

     

       319
       319
       -
       ```

     

       320
       320
       -
       zfs: Keep trying root import until it works

     

       321
       321
       -
       

     

       322
       322
       -
       Works around #11003.

     

       323
       323
       -
       

     

       324
       324
       -
       (cherry picked from commit 98b213a11041af39b39473906b595290e2a4e2f9)

     

       325
       325
       -
       

     

       326
       326
       -
       Reason: several people cannot boot with ZFS on NVMe

     

       327
       327
       -
       ```

     

       328
       328
       -
       

     

       329
       329
       -
       Other examples of reasons are:

     

       330
       330
       -
       

     

       331
       331
       -
       - Previously the build would fail due to, e.g., `getaddrinfo` not being defined

     

       332
       332
       -
       - The previous download links were all broken

     

       333
       333
       -
       - Crash when starting on some X11 systems

     

       83
       83
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       334
       84
        
       

     

       335
       85
        
       #### Acceptable backport criteria {#acceptable-backport-criteria}

     

       336
       86
        
       

     

       337
       337
       -
       The stable branch does have some changes which cannot be backported. Most notable are breaking changes. The desire is to have stable users be uninterrupted when updating packages.

     

       87
       87
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       338
       88
        
       

     

       339
       339
       -
       However, many changes are able to be backported, including:

     

       340
       340
       -
       - New Packages / Modules

     

       341
       341
       -
       - Security / Patch updates

     

       342
       342
       -
       - Version updates which include new functionality (but no breaking changes)

     

       343
       343
       -
       - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)

     

       344
       344
       -
       - Security critical applications (E.g. `firefox`)

+69

pkgs/README.md

···

       474
       474
        
           $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch

     

       475
       475
        
           ```

     

       476
       476
        
       

     

       477
       477
       +
       ## Deprecating/removing packages {#submitting-changes-deprecating-packages}

     

       478
       478
       +
       

     

       479
       479
       +
       There is currently no policy when to remove a package.

     

       480
       480
       +
       

     

       481
       481
       +
       Before removing a package, one should try to find a new maintainer or fix smaller issues first.

     

       482
       482
       +
       

     

       483
       483
       +
       ### Steps to remove a package from Nixpkgs {#steps-to-remove-a-package-from-nixpkgs}

     

       484
       484
       +
       

     

       485
       485
       +
       We use jbidwatcher as an example for a discontinued project here.

     

       486
       486
       +
       

     

       487
       487
       +
       1. Have Nixpkgs checked out locally and up to date.

     

       488
       488
       +
       1. Create a new branch for your change, e.g. `git checkout -b jbidwatcher`

     

       489
       489
       +
       1. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher`

     

       490
       490
       +
       1. Remove the package from the list of all packages (`pkgs/top-level/all-packages.nix`).

     

       491
       491
       +
       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.)

     

       492
       492
       +
       

     

       493
       493
       +
           For example in this case:

     

       494
       494
       +
       

     

       495
       495
       +
           ```

     

       496
       496
       +
           jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15

     

       497
       497
       +
           ```

     

       498
       498
       +
       

     

       499
       499
       +
           The throw message should explain in short why the package was removed for users that still have it installed.

     

       500
       500
       +
       

     

       501
       501
       +
       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.

     

       502
       502
       +
       1. Commit the changes. Explain again why the package was removed. If it was declared discontinued upstream, add a link to the source.

     

       503
       503
       +
       

     

       504
       504
       +
           ```ShellSession

     

       505
       505
       +
           $ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix

     

       506
       506
       +
           $ git commit

     

       507
       507
       +
           ```

     

       508
       508
       +
       

     

       509
       509
       +
           Example commit message:

     

       510
       510
       +
       

     

       511
       511
       +
           ```

     

       512
       512
       +
           jbidwatcher: remove

     

       513
       513
       +
       

     

       514
       514
       +
           project was discontinued in march 2021. the program does not work anymore because ebay changed the login.

     

       515
       515
       +
       

     

       516
       516
       +
           https://web.archive.org/web/20210315205723/http://www.jbidwatcher.com/

     

       517
       517
       +
           ```

     

       518
       518
       +
       

     

       519
       519
       +
       1. Push changes to your GitHub fork with `git push`

     

       520
       520
       +
       1. Create a pull request against Nixpkgs. Mention the package maintainer.

     

       521
       521
       +
       

     

       522
       522
       +
       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)

     

       523
       523
       +
       

     

       477
       524
        
       ## Testing changes | Package tests {#sec-package-tests}

     

       478
       525
        
       

     

       479
       526
        
       To run the main types of tests locally:

     
···

       696
       743
        
       

     

       697
       744
        
       ##### Comments

     

       698
       745
        
       ```

     

       746
       746
       +
       

     

       747
       747
       +
       ## (Security)

     

       748
       748
       +
       

     

       749
       749
       +
       ### Submitting security fixes {#submitting-changes-submitting-security-fixes}

     

       750
       750
       +
       

     

       751
       751
       +
       Security fixes are submitted in the same way as other changes and thus the same guidelines apply.

     

       752
       752
       +
       

     

       753
       753
       +
       - If a new version fixing the vulnerability has been released, update the package;

     

       754
       754
       +
       - If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.

     

       755
       755
       +
         The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:

     

       756
       756
       +
       

     

       757
       757
       +
         ```nix

     

       758
       758
       +
         (fetchpatch {

     

       759
       759
       +
           name = "CVE-2019-11068.patch";

     

       760
       760
       +
           url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";

     

       761
       761
       +
           hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";

     

       762
       762
       +
         })

     

       763
       763
       +
         ```

     

       764
       764
       +
       

     

       765
       765
       +
       If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch.

     

       766
       766
       +
       

     

       767
       767
       +
       Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`.