pyrox.dev
1# Contributing to Nixpkgs packages
2
3This document is for people wanting to contribute specifically to the package collection in Nixpkgs.
4See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general information.
5
6## Overview
7
8- [`top-level`](./top-level): Entrypoints, package set aggregations
9 - [`impure.nix`](./top-level/impure.nix), [`default.nix`](./top-level/default.nix), [`config.nix`](./top-level/config.nix): Definitions for the evaluation entry point of `import <nixpkgs>`
10 - [`stage.nix`](./top-level/stage.nix), [`all-packages.nix`](./top-level/all-packages.nix), [`by-name-overlay.nix`](./top-level/by-name-overlay.nix), [`splice.nix`](./top-level/splice.nix): Definitions for the top-level attribute set made available through `import <nixpkgs> {…}`
11 - `*-packages.nix`, [`linux-kernels.nix`](./top-level/linux-kernels.nix), [`unixtools.nix`](./top-level/unixtools.nix): Aggregations of nested package sets defined in `development`
12 - [`aliases.nix`](./top-level/aliases.nix), [`python-aliases.nix`](./top-level/python-aliases.nix): Aliases for package definitions that have been renamed or removed
13 - `release*.nix`, [`make-tarball.nix`](./top-level/make-tarball.nix), [`packages-config.nix`](./top-level/packages-config.nix), [`metrics.nix`](./top-level/metrics.nix), [`nixpkgs-basic-release-checks.nix`](./top-level/nixpkgs-basic-release-checks.nix): Entry-points and utilities used by Hydra for continuous integration
14- [`development`](./development)
15 - `*-modules`, `*-packages`, `*-pkgs`: Package definitions for nested package sets
16 - All other directories loosely categorise top-level package definitions, see [category hierarchy][categories]
17- [`build-support`](./build-support): [Builders](https://nixos.org/manual/nixpkgs/stable/#part-builders)
18 - `fetch*`: [Fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers)
19- [`stdenv`](./stdenv): [Standard environment](https://nixos.org/manual/nixpkgs/stable/#part-stdenv)
20- [`pkgs-lib`](./pkgs-lib): Definitions for utilities that need packages but are not needed for packages
21- [`test`](./test): Tests not directly associated with any specific packages
22- [`by-name`](./by-name): Top-level packages organised by name ([docs](./by-name/README.md))
23- All other directories loosely categorise top-level packages definitions, see [category hierarchy][categories]
24
25## Quick Start to Adding a Package
26
27We welcome new contributors of new packages to Nixpkgs, arguably the greatest software database known.
28However, each new package comes with a cost for the maintainers, Continuous Integration, caching servers and users downloading Nixpkgs.
29
30Before adding a new package, please consider the following questions:
31
32* Is the package ready for general use?
33 We don't want to include projects that are too immature or are going to be abandoned immediately.
34 In case of doubt, check with upstream.
35* Does the project have a clear license statement?
36 Remember that software is unfree by default (all rights reserved), and merely providing access to the source code does not imply its redistribution.
37 In case of doubt, ask upstream.
38* How realistic is it that it will be used by other people?
39 It's good that nixpkgs caters to various niches, but if it's a niche of 5 people it's probably too small.
40 A good estimate is checking upstream issues and pull requests, or other software repositories.
41 * Library packages should have at least one dependent.
42 If possible, that dependent should be packaged in the same PR the library is added in, as a sanity check.
43 If it is not possible to package the dependent, a minimal test program should be added to `passthru.tests`.
44* Is the software actively maintained upstream?
45 Especially packages that are security-critical, rely on fast-moving dependencies, or affect data integrity should see regular maintenance.
46* Are you willing to maintain the package?
47 You should care enough about the package to be willing to keep it up and running for at least one complete Nixpkgs' release life-cycle.
48 * In case you are not able to maintain the package you wrote, you can seek someone to fill that role, effectively adopting the package.
49
50If any of these questions' answer is no, then you should probably not add the package.
51
52Special care has to be taken with security-critical software components.
53Because entries in the Nix store are inert and do nothing by themselves, packages should be considered by their intended use, e.g. when used together with a NixOS module.
54
55* Any package that immediately would need to be tagged with `meta.knownVulnerabilities` is unlikely to be fit for nixpkgs.
56* Any package depending on a known-vulnerable library should be considered carefully.
57* Packages typically used with untrusted data should have a maintained and responsible upstream.
58 For example:
59 * Any package which does not follow upstream security policies should be considered vulnerable.
60 In particular, packages that vendor or fork web engines like Blink, Gecko or Webkit need to keep up with the frequent updates of those projects.
61 * Any security-critical fast-moving package such as Chrome or Firefox (or their forks) must have at least one active committer among the maintainers.
62 This ensures no critical fixes are delayed unnecessarily, endangering unsuspecting users.
63 * Services which typically work on web traffic are working on untrusted input.
64 * Data (such as archives or rich documents) commonly shared over untrusted channels (e.g. email) is untrusted.
65* Applications in the Unix authentication stack such as PAM/D-Bus modules or SUID binaries should be considered carefully, and should have a maintained and responsible upstream.
66* Encryption libraries should have a maintained and responsible upstream.
67* Security-critical components that are part of larger packages should be unvendored (=use the nixpkgs package as dependency, instead of vendored and pinned sources).
68* A "responsible upstream" includes various aspects, such as:
69 * channels to disclose security concerns
70 * being responsive to security concerns, providing fixes or workarounds
71 * transparent public disclosure of security issues when they are found or fixed
72 * These aspects are sometimes hard to verify, in which case an upstream that is not known to be irresponsible should be considered as responsible.
73* Source-available software should be built from source where possible.
74 Binary blobs risk supply chain attacks and vendored outdated libraries.
75
76This section describes a general framework of understanding and exceptions might apply.
77
78Luckily it's pretty easy to maintain your own package set with Nix, which can then be added to the [Nix User Repository](https://github.com/nix-community/nur) project.
79
80---
81
82Now that this is out of the way.
83To add a package to Nixpkgs:
84
851. Checkout the Nixpkgs source tree:
86
87 ```ShellSession
88 $ git clone https://github.com/NixOS/nixpkgs
89 $ cd nixpkgs
90 ```
91
922. Create a package directory `pkgs/by-name/so/some-package` where `some-package` is the package name and `so` is the lowercased 2-letter prefix of the package name:
93
94 ```ShellSession
95 $ mkdir -p pkgs/by-name/so/some-package
96 ```
97
98 For more detailed information, see [here](./by-name/README.md).
99
1003. Create a `package.nix` file in the package directory, containing a Nix expression — a piece of code that describes how to build the package.
101 In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store.
102
103 ```ShellSession
104 $ emacs pkgs/by-name/so/some-package/package.nix
105 $ git add pkgs/by-name/so/some-package/package.nix
106 ```
107
108 If the package is written in a language other than C, you should use [the corresponding language framework](https://nixos.org/manual/nixpkgs/stable/#chap-language-support).
109
110 You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done, some of which are also using the [category hierarchy](#category-hierarchy).
111 Here are some good ones:
112
113 - GNU Hello: [`pkgs/by-name/he/hello/package.nix`](./by-name/he/hello/package.nix).
114 Trivial package, which specifies some `meta` attributes which is good practice.
115
116 - GNU cpio: [`pkgs/by-name/cp/cpio/package.nix`](./by-name/cp/cpio/package.nix).
117 Also a simple package.
118 The generic builder in `stdenv` does everything for you.
119 It has no dependencies beyond `stdenv`.
120
121 - GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp`](development/libraries/gmp).
122 Also done by the generic builder, but has a dependency on `m4`.
123
124 - Pan, a GTK-based newsreader: [`pkgs/by-name/pa/pan/package.nix`](./by-name/pa/pan/package.nix).
125 Has an optional dependency on `gspell`, which is only built if `spellCheck` is `true`.
126
127 - Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](servers/http/apache-httpd/2.4.nix).
128 A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.
129
130 - buildMozillaMach: [`pkgs/build-support/build-mozilla-mach/default.nix`](./build-support/build-mozilla-mach/default.nix).
131 A reusable build function for Firefox, Thunderbird and Librewolf.
132
133 - JDiskReport, a Java utility: [`pkgs/by-name/jd/jdiskreport/package.nix`](./by-name/jd/jdiskreport/package.nix).
134 Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.
135
136 - XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](top-level/perl-packages.nix) (search for the `XMLSimple` attribute).
137 Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.
138
139 - Discord Game SDK: [`pkgs/by-name/di/discord-gamesdk/package.nix`](./by-name/di/discord-gamesdk/package.nix).
140 Shows how binary-only packages can be supported.
141 In particular, the `autoPatchelfHook` is used to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.
142
143 Some notes:
144
145 - Add yourself as the maintainer of the package.
146
147 - If this is your first time contributing (welcome!), [add yourself to the maintainers list](../maintainers/README.md#how-to-become-a-maintainer) in a separate commit.
148
149 - All other [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes are optional, but it’s still a good idea to provide at least the `description`, `homepage` and [`license`](https://nixos.org/manual/nixpkgs/stable/#sec-meta-license).
150
151 - The exact syntax and semantics of the Nix expression language, including the built-in functions, are [Nix language reference](https://nixos.org/manual/nix/stable/language/).
152
1535. To test whether the package builds, run the following command from the root of the nixpkgs source tree:
154
155 ```ShellSession
156 $ nix-build -A some-package
157 ```
158
159 where `some-package` should be the package name.
160 You may want to add the flag `-K` to keep the temporary build directory in case something fails.
161 If the build succeeds, a symlink `./result` to the package in the Nix store is created.
162
1636. If you want to install the package into your profile (optional), do
164
165 ```ShellSession
166 $ nix-env -f . -iA libfoo
167 ```
168
1697. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account.
170
171## Commit conventions
172
173- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
174
175- Format the commit messages in the following way:
176
177 ```
178 (pkg-name): (from -> to | init at version | refactor | etc)
179
180 (Motivation for change. Link to release notes. Additional information.)
181 ```
182
183 Examples:
184
185 * nginx: init at 2.0.1
186 * firefox: 54.0.1 -> 55.0
187
188 https://www.mozilla.org/en-US/firefox/55.0/releasenotes/
189
190(using "→" instead of "->" is also accepted)
191
192Using the `(pkg-name):` prefix is important beyond just being a convention: it queues automatic builds by CI.
193More sophisticated prefixes are also possible:
194
195| Message | Automatic Builds |
196|--------------------------------------------------------------------------|------------------------------------------------------------|
197| `vim: 1.0.0 -> 2.0.0` | `vim` |
198| `vagrant: fix dependencies for version 2.0.2` | `vagrant` |
199| `python3{9,10}Packages.requests: 1.0.0 -> 2.0.0` | `python39Packages.requests`, `python310Packages.requests` |
200| `python312.pkgs.numpy,python313.pkgs.scipy: fix build` | `python312.pkgs.numpy` , `python313.pkgs.scipy` |
201
202When opening a PR with multiple commits, CI creates a single build job for all detected packages.
203If `passthru.tests` attributes are available, these will be built as well.
204
205If the title of the _PR_ begins with `WIP:` or contains `[WIP]` anywhere, its packages are not built automatically.
206Other than that, PR titles have meaning only for humans.
207It is recommended to keep the PR title in sync with the commit title, to make it easier to find.
208For PRs with multiple commits, the PR title should be a general summary of these commits.
209
210> [!NOTE]
211> Marking a PR as a draft does not prevent automatic builds.
212
213## Category Hierarchy
214[categories]: #category-hierarchy
215
216Most top-level packages are organised in a loosely-categorised directory hierarchy in this directory.
217See the [overview](#overview) for which directories are part of this.
218
219This category hierarchy is partially deprecated and will be migrated away over time.
220The new `pkgs/by-name` directory ([docs](./by-name/README.md)) should be preferred instead.
221The category hierarchy may still be used for packages that should be imported using an alternate `callPackage`, such as `python3Packages.callPackage` or `libsForQt5.callPackage`.
222
223If that is the case for a new package, here are some rules for picking the right category.
224Many packages fall under several categories; what matters is the _primary_ purpose of a package.
225For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.
226
227<details>
228<summary>Categories</summary>
229
230**If it’s used to support _software development_:**
231
232- **If it’s a _library_ used by other packages:**
233
234 - `development/libraries` (e.g. `libxml2`)
235
236- **If it’s a _compiler_:**
237
238 - `development/compilers` (e.g. `gcc`)
239
240- **If it’s an _interpreter_:**
241
242 - `development/interpreters` (e.g. `guile`)
243
244- **If it’s a (set of) development _tool(s)_:**
245
246 - **If it’s a _parser generator_ (including lexers):**
247
248 - `development/tools/parsing` (e.g. `bison`, `flex`)
249
250 - **If it’s a _build manager_:**
251
252 - `development/tools/build-managers` (e.g. `gnumake`)
253
254 - **If it’s a _language server_:**
255
256 - `development/tools/language-servers` (e.g. `ccls` or `nil`)
257
258 - **Else:**
259
260 - `development/tools/misc` (e.g. `binutils`)
261
262- **Else:**
263
264 - `development/misc`
265
266**If it’s a (set of) _tool(s)_:**
267
268(A tool is a relatively small program, especially one intended to be used non-interactively.)
269
270- **If it’s for _networking_:**
271
272 - `tools/networking` (e.g. `wget`)
273
274- **If it’s for _text processing_:**
275
276 - `tools/text` (e.g. `diffutils`)
277
278- **If it’s a _system utility_, i.e., something related or essential to the operation of a system:**
279
280 - `tools/system` (e.g. `cron`)
281
282- **If it’s an _archiver_ (which may include a compression function):**
283
284 - `tools/archivers` (e.g. `zip`, `tar`)
285
286- **If it’s a _compression_ program:**
287
288 - `tools/compression` (e.g. `gzip`, `bzip2`)
289
290- **If it’s a _security_-related program:**
291
292 - `tools/security` (e.g. `nmap`, `gnupg`)
293
294- **Else:**
295
296 - `tools/misc`
297
298**If it’s a _shell_:**
299
300- `shells` (e.g. `bash`)
301
302**If it’s a _server_:**
303
304- **If it’s a web server:**
305
306 - `servers/http` (e.g. `apache-httpd`)
307
308- **If it’s an implementation of the X Windowing System:**
309
310 - `servers/x11` (e.g. `xorg` — this includes the client libraries and programs)
311
312- **Else:**
313
314 - `servers/misc`
315
316**If it’s a _desktop environment_:**
317
318- `desktops` (e.g. `kde`, `gnome`, `enlightenment`)
319
320**If it’s a _window manager_:**
321
322- `applications/window-managers` (e.g. `awesome`, `stumpwm`)
323
324**If it’s an _application_:**
325
326A (typically large) program with a distinct user interface, primarily used interactively.
327
328- **If it’s a _version management system_:**
329
330 - `applications/version-management` (e.g. `subversion`)
331
332- **If it’s a _terminal emulator_:**
333
334 - `applications/terminal-emulators` (e.g. `alacritty` or `rxvt` or `termite`)
335
336- **If it’s a _file manager_:**
337
338 - `applications/file-managers` (e.g. `mc` or `ranger` or `pcmanfm`)
339
340- **If it’s for _video playback / editing_:**
341
342 - `applications/video` (e.g. `vlc`)
343
344- **If it’s for _graphics viewing / editing_:**
345
346 - `applications/graphics` (e.g. `gimp`)
347
348- **If it’s for _networking_:**
349
350 - **If it’s a _mailreader_:**
351
352 - `applications/networking/mailreaders` (e.g. `thunderbird`)
353
354 - **If it’s a _newsreader_:**
355
356 - `applications/networking/newsreaders` (e.g. `pan`)
357
358 - **If it’s a _web browser_:**
359
360 - `applications/networking/browsers` (e.g. `firefox`)
361
362 - **Else:**
363
364 - `applications/networking/misc`
365
366- **Else:**
367
368 - `applications/misc`
369
370**If it’s _data_ (i.e., does not have a straight-forward executable semantics):**
371
372- **If it’s a _font_:**
373
374 - `data/fonts`
375
376- **If it’s an _icon theme_:**
377
378 - `data/icons`
379
380- **If it’s related to _SGML/XML processing_:**
381
382 - **If it’s an _XML DTD_:**
383
384 - `data/sgml+xml/schemas/xml-dtd` (e.g. `docbook`)
385
386 - **If it’s an _XSLT stylesheet_:**
387
388 (Okay, these are executable...)
389
390 - `data/sgml+xml/stylesheets/xslt` (e.g. `docbook-xsl`)
391
392- **If it’s a _theme_ for a _desktop environment_, a _window manager_ or a _display manager_:**
393
394 - `data/themes`
395
396**If it’s a _game_:**
397
398- `games`
399
400**Else:**
401
402- `misc`
403
404</details>
405
406# Conventions
407
408The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _should not_, _recommended_, _may_, and _optional_ in this section are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
409Only _emphasized_ words are to be interpreted in this way.
410
411## Package naming
412
413In Nixpkgs, there are generally three different names associated with a package:
414
415- The `pname` attribute of the derivation.
416 This is what most users see, in particular when using `nix-env`.
417
418- The attribute name used for the package in the [`pkgs/by-name` structure](./by-name/README.md) or in [`all-packages.nix`](./top-level/all-packages.nix), and when passing it as a dependency in recipes.
419
420- The filename for (the directory containing) the Nix expression.
421
422Most of the time, these are the same.
423For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the attribute name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.
424
425Follow these guidelines:
426
427- For the `pname` attribute:
428
429 - It _should_ be identical to the upstream package name.
430
431 - It _must not_ contain uppercase letters.
432
433 Example: Use `"mplayer"` instead of `"MPlayer"`
434
435- For the package attribute name:
436
437 - It _must_ be a valid identifier in Nix.
438
439 - If the `pname` starts with a digit, the attribute name _should_ be prefixed with an underscore.
440 Otherwise the attribute name _should not_ be prefixed with an underline.
441
442 Example: The corresponding attribute name for `0ad` should be `_0ad`.
443
444 - New attribute names _should_ be the same as the value in `pname`.
445
446 Hyphenated names _should not_ be converted to [snake case](https://en.wikipedia.org/wiki/Snake_case) or [camel case](https://en.wikipedia.org/wiki/Camel_case).
447 This was done historically, but is not necessary any more.
448 [The Nix language allows dashes in identifiers since 2012](https://github.com/NixOS/nix/commit/95c74eae269b2b9e4bc514581b5caa1d80b54acc).
449
450 - If there are multiple versions of a package, this _should_ be reflected in the attribute names in `all-packages.nix`.
451
452 Example: `json-c_0_9` and `json-c_0_11`
453
454 If there is an obvious “default” version, make an extra attribute.
455
456 Example: `json-c = json-c_0_9;`
457
458 See also [versioning][versioning].
459
460## Versioning
461[versioning]: #versioning
462
463These are the guidelines the `version` attribute of a package:
464
465- It _must_ start with a digit.
466 This is required for backwards-compatibility with [how `nix-env` parses derivation names](https://nix.dev/manual/nix/latest/command-ref/nix-env#selectors).
467
468 Example: `"0.3.1rc2"` or `"0-unstable-1970-01-01"`
469
470- If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit.
471 The date _must_ be in `"YYYY-MM-DD"` format.
472
473 Example: Given a project had its latest releases `2.2` in November 2021 and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.
474
475- If a project has no suitable preceding releases - e.g., no versions at all, or an incompatible versioning or tagging scheme - then the latest upstream version in the above schema should be `0`.
476
477 Example: Given a project that has no tags or released versions at all, or applies versionless tags like `latest` or `YYYY-MM-DD-Build`, a commit authored on March 15, 2022 would have `version = "0-unstable-2022-03-15"`.
478
479Because every version of a package in Nixpkgs creates a potential maintenance burden, old versions of a package should not be kept unless there is a good reason to do so.
480For instance, Nixpkgs contains several versions of GCC because other packages don’t build with the latest version of GCC.
481Other examples are having both the latest stable and latest pre-release version of a package, or to keep several major releases of an application that differ significantly in functionality.
482
483If there is only one version of a package, its Nix expression should be named (e.g) `pkgs/by-name/xy/xyz/package.nix`.
484If there are multiple versions, this should be reflected in the attribute name.
485If you wish to share code between the Nix expressions of each version, you cannot rely upon `pkgs/by-name`'s automatic attribute creation, and must create the attributes yourself in `all-packages.nix`.
486See also [`pkgs/by-name/README.md`'s section on this topic](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/README.md#recommendation-for-new-packages-with-multiple-versions).
487
488## Meta attributes
489
490The `meta` attribute set should always be placed last in the derivativion and any other "meta"-like attribute sets like `passthru` should be written before it.
491
492* `meta.description` must:
493 * Be short, just one sentence.
494 * Be capitalized.
495 * Not start with the definite or an indefinite article.
496 * Not start with the package name.
497 * More generally, it should not refer to the package name.
498 * Not end with a period (or any punctuation for that matter).
499 * Provide factual information.
500 * Avoid subjective language.
501* `meta.license` must be set and match the upstream license.
502 * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`.
503 * If in doubt, try to contact the upstream developers for clarification.
504* `meta.mainProgram` must be set to the name of the executable which facilitates the primary function or purpose of the package, if there is such an executable in `$bin/bin/` (or `$out/bin/`, if there is no `"bin"` output).
505 * Packages that only have a single executable in the applicable directory above should set `meta.mainProgram`.
506 For example, the package `ripgrep` only has a single executable `rg` under `$out/bin/`, so `ripgrep.meta.mainProgram` is set to `"rg"`.
507 * Packages like `polkit_gnome` that have no executables in the applicable directory should not set `meta.mainProgram`.
508 * Packages like `e2fsprogs` that have multiple executables, none of which can be considered the main program, should not set `meta.mainProgram`.
509 * Packages which are not primarily used for a single executable do not need to set `meta.mainProgram`.
510 * Always prefer using a hardcoded string (don't use `pname`, for example).
511 * When in doubt, ask for reviewer input.
512* `meta.maintainers` must be set for new packages.
513
514See the Nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes).
515
516## Import From Derivation
517
518[Import From Derivation](https://nixos.org/manual/nix/unstable/language/import-from-derivation) (IFD) is disallowed in Nixpkgs for performance reasons:
519[Hydra](https://github.com/NixOS/hydra) evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical.
520
521Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead.
522
523## `overrideAttrs` and `overridePythonAttrs`
524
525Please do not introduce new uses of `overrideAttrs` or `overridePythonAttrs` in Nixpkgs.
526These functions are useful for out-of-tree code because they allow easy overriding a package without changing its source in Nixpkgs, but when contributing to Nixpkgs you *can* change the source of other packages. So instead of using the escape hatch that is overriding, you should try to provide proper support for the functionality you need, in ways that are visible and can be understood and accounted for by the maintainers of the patched package.
527Using `overrideAttrs` and `overridePythonAttrs` in Nixpkgs causes maintainability problems:
528
529* It's easy for multiple packages to end up duplicating basically the same override without noticing.
530* It's not clear when working on an overridden package that it's being overridden elsewhere in Nixpkgs, so `overrideAttrs` and `overridePythonAttrs` are fragile and can break accidentally when the overridden package is changed.
531* Package maintainers will not be requested for review of overrides, even though they are likely to have important knowledge about the package.
532* It is easy for overridden packages to be forgotten and remain around long after they are no longer necessary.
533* Dependency closures end up being bigger than necessary due to unnecessarily including multiple versions of the same package.
534
535Instead, keep all instances of the same package next to each other, and try to minimize how many different instances of a package are in Nixpkgs.
536If you need a patch applied to a dependency, discuss with the maintainer of that dependency whether it would be acceptable to apply to the main version of the package.
537If you need a different version of a dependency, first try modifying your package to work with the version in Nixpkgs — it's often not very hard! — and if that's not possible, try to factor out a function that can build multiple versions of the package, including the main version.
538If you need to enable or disable optional functionality of a dependency, add an explicit flag to the package and use `override` instead.
539
540## Sources
541
542Always fetch source files using [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/unstable/#chap-pkgs-fetchers).
543Use reproducible sources with a high degree of availability.
544Prefer protocols that support proxies.
545
546A list of schemes for `mirror://` URLs can be found in [`pkgs/build-support/fetchurl/mirrors.nix`](build-support/fetchurl/mirrors.nix), and is supported by [`fetchurl`](https://nixos.org/manual/nixpkgs/unstable/#fetchurl).
547Other fetchers which end up relying on `fetchurl` may also support mirroring.
548
549The preferred source hash type is `sha256`.
550
551Examples going from bad to best practices:
552
553- Bad: Uses `git://` which won't be proxied.
554
555 ```nix
556 {
557 src = fetchgit {
558 url = "git://github.com/NixOS/nix.git";
559 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
560 hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
561 };
562 }
563 ```
564
565- Better: This is ok, but an archive fetch will still be faster.
566
567 ```nix
568 {
569 src = fetchgit {
570 url = "https://github.com/NixOS/nix.git";
571 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
572 hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
573 };
574 }
575 ```
576
577- Best: Fetches a snapshot archive for the given revision.
578
579 ```nix
580 {
581 src = fetchFromGitHub {
582 owner = "NixOS";
583 repo = "nix";
584 rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
585 hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
586 };
587 }
588 ```
589
590> [!Note]
591> When fetching from GitHub, always reference revisions by their full commit hash.
592> GitHub shares commit hashes among all forks and returns `404 Not Found` when a short commit hash is ambiguous.
593> It already happened in Nixpkgs for short, 6-character commit hashes.
594>
595> Pushing large amounts of auto generated commits into forks is a practical vector for a denial-of-service attack, and was already [demonstrated against GitHub Actions Beta](https://blog.teddykatz.com/2019/11/12/github-actions-dos.html).
596
597## Patches
598
599Sometimes, changes are needed to the source to allow building a derivation in nixpkgs, or to get earlier access to an upstream fix or improvement.
600When using the `patches` parameter to `mkDerivation`, make sure the patch name clearly describes the reason for the patch, or add a comment.
601
602> [!Note]
603> The version of the package does not need to be changed just because a patch is applied.
604> Declarative package installations don't depend on the version, while imperative `nix-env` installations can use [`upgrade --eq/leq/--always`](https://nix.dev/manual/nix/2.25/command-ref/nix-env/upgrade#flags).
605>
606> See [Versioning](#versioning) for details on package versioning.
607
608The following describes two ways to include the patch.
609Regardless of how the patch is included, you _must_ ensure its purpose is clear and obvious.
610This enables other maintainers to more easily determine when old patches are no longer required.
611Typically, you can improve clarity with carefully considered filenames, attribute names, and/or comments; these should explain the patch's _intention_.
612Additionally, it may sometimes be helpful to clarify _how_ it resolves the issue.
613For example: _"fix gcc14 build by adding missing include"_.
614
615### Fetching patches
616
617In the interest of keeping our maintenance burden and the size of Nixpkgs to a minimum, patches already merged upstream or published elsewhere _should_ be retrieved using `fetchpatch2`:
618
619```nix
620{
621 patches = [
622 (fetchpatch2 {
623 name = "make-no-atomics-a-soft-failure.patch";
624 url = "https://github.com/boostorg/math/commit/7d482f6ebc356e6ec455ccb5f51a23971bf6ce5b.patch?full_index=1";
625 hash = "sha256-9Goa0NTUdSOs1Vm+FnkoSFhw0o8ZLNOw6cLUqCVnF5Y=";
626 })
627 ];
628}
629```
630
631> [!Warning]
632> If the patch file contains short commit hashes, use `fetchpatch` instead of `fetchpatch2` ([tracking issue](https://github.com/NixOS/nixpkgs/issues/257446)).
633> This is the case if the patch contains a line similar to `index 0c97fcc35..f533e464a 100644`.
634> Depending on the patch source it is possible to expand the commit hash, in which case using `fetchpatch2` is acceptable (e.g. GitHub supports appending `?full_index=1` to the URL, as seen above).
635
636If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch2`.
637Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details.
638
639When adding patches in this manner you should be reasonably sure that the used URL is stable.
640Patches referencing open pull requests will change when the PR is updated and code forges (such as GitHub) usually garbage collect commits that are no longer reachable due to rebases/amends.
641
642### Vendoring patches
643
644In the following cases, a `.patch` file _should_ be added to Nixpkgs repository, instead of retrieved:
645
646- solves problems unique to packaging in Nixpkgs
647- cannot be fetched easily
648- has a high chance to disappear in the future due to unstable or unreliable URLs
649
650The latter avoids link rot when the upstream abandons, squashes or rebases their change, in which case the commit may get garbage-collected.
651
652```nix
653{ patches = [ ./0001-add-missing-include.patch ]; }
654```
655
656If you do need to do create this sort of patch file, one way to do so is with git:
657
6581. Move to the root directory of the source code you're patching.
659
660 ```ShellSession
661 $ cd the/program/source
662 ```
663
6642. If a git repository is not already present, create one and stage all of the source files.
665
666 ```ShellSession
667 $ git init
668 $ git add -A
669 ```
670
6713. Edit some files to make whatever changes need to be included in the patch.
672
6734. Use git to create a diff, and pipe the output to a patch file:
674
675 ```ShellSession
676 $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch
677 ```
678
679## Deprecating/removing packages
680
681There is currently no policy when to remove a package.
682
683Before removing a package, one should try to find a new maintainer or fix smaller issues first.
684
685### Steps to remove a package from Nixpkgs
686
687We use jbidwatcher as an example for a discontinued project here.
688
6891. Have Nixpkgs checked out locally and up to date.
6901. Create a new branch for your change, e.g. `git checkout -b jbidwatcher`
6911. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher`
6921. Remove the package from the list of all packages (`pkgs/top-level/all-packages.nix`).
6931. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/applications/editors/vim/plugins/aliases.nix`.
694 Package sets typically do not have aliases, so we can't add them there.)
695
696 For example in this case:
697
698 ```nix
699 {
700 jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15
701 }
702 ```
703
704 The throw message should explain in short why the package was removed for users that still have it installed.
705
7061. Test if the changes introduced any issues by running `nix-env -qaP -f . --show-trace`.
707 It should show the list of packages without errors.
7081. Commit the changes.
709 Explain again why the package was removed.
710 If it was declared discontinued upstream, add a link to the source.
711
712 ```ShellSession
713 $ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix
714 $ git commit
715 ```
716
717 Example commit message:
718
719 ```
720 jbidwatcher: remove
721
722 project was discontinued in march 2021. the program does not work anymore because ebay changed the login.
723
724 https://web.archive.org/web/20210315205723/http://www.jbidwatcher.com/
725 ```
726
7271. Push changes to your GitHub fork with `git push`
7281. Create a pull request against Nixpkgs.
729 Mention the package maintainer.
730
731This is how the pull request looks like in this case: [https://github.com/NixOS/nixpkgs/pull/116470](https://github.com/NixOS/nixpkgs/pull/116470)
732
733## Package tests
734
735To run the main types of tests locally:
736
737- Run package-internal tests with `nix-build --attr pkgs.PACKAGE.passthru.tests`
738- Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTests.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix`
739- Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix`
740- See `lib/tests/NAME.nix` for instructions on running specific library tests
741
742Tests are important to ensure quality and make reviews and automatic updates easy.
743
744The following types of tests exists:
745
746* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs.
747 They exercise both NixOS modules and the packaged programs used within them.
748 For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.
749* Nix **package tests** are a lightweight alternative to NixOS module tests.
750 They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.
751* The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.
752
753Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
754
755### Writing inline package tests
756
757For very simple tests, they can be written inline:
758
759```nix
760# ... ,
761{ yq-go }:
762
763buildGoModule rec {
764 # …
765
766 passthru.tests = {
767 simple = runCommand "${pname}-test" { } ''
768 echo "test: 1" | ${yq-go}/bin/yq eval -j > $out
769 [ "$(cat $out | tr -d $'\n ')" = '{"test":1}' ]
770 '';
771 };
772}
773```
774
775Any derivation can be specified as a test, even if it's in a different file.
776Such a derivation that implements a test can depend on the package under test, even in the presence of `overrideAttrs`.
777
778In the following example, `(my-package.overrideAttrs f).passthru.tests` will work as expected, as long as the definition of `tests` does not rely on the original `my-package` or overrides all occurrences of `my-package`:
779
780```nix
781# my-package/default.nix
782{ stdenv, callPackage }:
783stdenv.mkDerivation (finalAttrs: {
784 # ...
785 passthru.tests.example = callPackage ./example.nix { my-package = finalAttrs.finalPackage; };
786})
787```
788
789```nix
790# my-package/example.nix
791{
792 runCommand,
793 lib,
794 my-package,
795 ...
796}:
797runCommand "my-package-test"
798 {
799 nativeBuildInputs = [ my-package ];
800 src = lib.sources.sourcesByRegex ./. [
801 ".*.in"
802 ".*.expected"
803 ];
804 }
805 ''
806 my-package --help
807 my-package <example.in >example.actual
808 diff -U3 --color=auto example.expected example.actual
809 mkdir $out
810 ''
811```
812
813### Writing larger package tests
814[larger-package-tests]: #writing-larger-package-tests
815
816This is an example using the `phoronix-test-suite` package with the current best practices.
817
818Add the tests in `passthru.tests` to the package definition like this:
819
820```nix
821{
822 stdenv,
823 lib,
824 fetchurl,
825 callPackage,
826}:
827
828stdenv.mkDerivation {
829 # …
830
831 passthru.tests = {
832 simple-execution = callPackage ./tests.nix { };
833 };
834
835 meta = {
836 # …
837 };
838}
839```
840
841Create `tests.nix` in the package directory:
842
843```nix
844{ runCommand, phoronix-test-suite }:
845
846let
847 inherit (phoronix-test-suite) pname version;
848
849in
850runCommand "${pname}-tests" { meta.timeout = 60; } ''
851 # automatic initial setup to prevent interactive questions
852 ${phoronix-test-suite}/bin/phoronix-test-suite enterprise-setup >/dev/null
853 # get version of installed program and compare with package version
854 if [[ `${phoronix-test-suite}/bin/phoronix-test-suite version` != *"${version}"* ]]; then
855 echo "Error: program version does not match package version"
856 exit 1
857 fi
858 # run dummy command
859 ${phoronix-test-suite}/bin/phoronix-test-suite dummy_module.dummy-command >/dev/null
860 # needed for Nix to register the command as successful
861 touch $out
862''
863```
864
865### Running package tests
866
867You can run these tests with:
868
869```ShellSession
870$ cd path/to/nixpkgs
871$ nix-build -A phoronix-test-suite.tests
872```
873
874### Examples of package tests
875
876Here are examples of package tests:
877
878- [Jasmin compile test](by-name/ja/jasmin/test-assemble-hello-world/default.nix)
879- [Lobster compile test](development/compilers/lobster/test-can-run-hello-world.nix)
880- [Spacy annotation test](development/python-modules/spacy/annotation-test/default.nix)
881- [Libtorch test](development/libraries/science/math/libtorch/test/default.nix)
882- [Multiple tests for nanopb](./by-name/na/nanopb/package.nix)
883
884### Linking NixOS module tests to a package
885
886Like [package tests][larger-package-tests] as shown above, [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests) can also be linked to a package, so that the tests can be easily run when changing the related package.
887
888For example, assuming we're packaging `nginx`, we can link its module test via `passthru.tests`:
889
890```nix
891{
892 stdenv,
893 lib,
894 nixosTests,
895}:
896
897stdenv.mkDerivation {
898 # ...
899
900 passthru.tests = {
901 nginx = nixosTests.nginx;
902 };
903
904 # ...
905}
906```
907
908## Automatic package updates
909[automatic-package-updates]: #automatic-package-updates
910
911Nixpkgs periodically tries to update all packages that have a `passthru.updateScript` attribute.
912
913> [!Note]
914> A common pattern is to use the [`nix-update-script`](../pkgs/by-name/ni/nix-update/nix-update-script.nix) attribute provided in Nixpkgs, which runs [`nix-update`](https://github.com/Mic92/nix-update):
915>
916> ```nix
917> { stdenv, nix-update-script }:
918> stdenv.mkDerivation {
919> # ...
920> passthru.updateScript = nix-update-script { };
921> }
922> ```
923>
924> For simple packages, this is often enough, and will ensure that the package is updated automatically by [`nixpkgs-update`](https://github.com/nix-community/nixpkgs-update) when a new version is released.
925> The [update bot](https://nix-community.org/update-bot) runs periodically to attempt to automatically update packages, and will run `passthru.updateScript` if set.
926> While not strictly necessary if the project is listed on [Repology](https://repology.org), using `nix-update-script` allows the package to update via many more sources (e.g. GitHub releases).
927
928The `passthru.updateScript` attribute can contain one of the following:
929
930- an executable file, either on the file system:
931
932 ```nix
933 { stdenv }:
934 stdenv.mkDerivation {
935 # ...
936 passthru.updateScript = ./update.sh;
937 }
938 ```
939
940 or inside the expression itself:
941
942 ```nix
943 { stdenv, writeScript }:
944 stdenv.mkDerivation {
945 # ...
946 passthru.updateScript = writeScript "update-zoom-us" ''
947 #!/usr/bin/env nix-shell
948 #!nix-shell -i bash -p curl pcre2 common-updater-scripts
949
950 set -eu -o pipefail
951
952 version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcre2grep -o1 '/(([0-9]\.?)+)/')"
953 update-source-version zoom-us "$version"
954 '';
955 }
956 ```
957
958- a list, a script file followed by arguments to be passed to it:
959
960 ```nix
961 { stdenv }:
962 stdenv.mkDerivation {
963 # ...
964 passthru.updateScript = [
965 ../../update.sh
966 pname
967 "--requested-release=unstable"
968 ];
969 }
970 ```
971
972- an attribute set containing:
973 - `command`
974
975 A string or list in the [format expected by `passthru.updateScript`][automatic-package-updates]
976
977 - `attrPath` (optional)
978
979 A string containing the canonical attribute path for the package.
980
981 If present, it will be passed to the update script instead of the attribute path on which the package was discovered during Nixpkgs traversal.
982
983 - `supportedFeatures` (optional)
984
985 A list of the [extra features the script supports][supported-features].
986
987 ```nix
988 { stdenv }:
989 stdenv.mkDerivation rec {
990 pname = "my-package";
991 # ...
992 passthru.updateScript = {
993 command = [
994 ../../update.sh
995 pname
996 ];
997 attrPath = pname;
998 supportedFeatures = [
999 # ...
1000 ];
1001 };
1002 }
1003 ```
1004
1005### How are update scripts executed?
1006
1007Update scripts are to be invoked by the [automatic package update script](../maintainers/scripts/update.nix).
1008You can run `nix-shell maintainers/scripts/update.nix` in the root of Nixpkgs repository for information on how to use it.
1009`update.nix` offers several modes for selecting packages to update, and it will execute update scripts for all matched packages that have an `updateScript` attribute.
1010
1011Update scripts will be run inside the [Nixpkgs development shell](../shell.nix), providing access to some useful tools for CI.
1012Furthermore each update script will be passed the following environment variables:
1013
1014- [`UPDATE_NIX_NAME`] – content of the `name` attribute of the updated package
1015- [`UPDATE_NIX_PNAME`] – content of the `pname` attribute of the updated package
1016- [`UPDATE_NIX_OLD_VERSION`] – content of the `version` attribute of the updated package
1017- [`UPDATE_NIX_ATTR_PATH`] – attribute path the `update.nix` discovered the package on (or the package's specified `attrPath` when available).
1018 Example: `pantheon.elementary-terminal`
1019
1020> [!Note]
1021> An update script will be usually run from the root of the Nixpkgs repository, but you should not rely on that.
1022> Also note that `update.nix` executes update scripts in parallel by default, so you should avoid running `git commit` or any other commands that cannot handle that.
1023
1024While update scripts should not create commits themselves, `update.nix` supports automatically creating commits when running it with `--argstr commit true`.
1025If you need to customize commit message, you can have the update script implement the `commit` feature.
1026
1027### Supported features
1028[update-script-supported-features]: #supported-features
1029
1030- `commit`
1031
1032 This feature allows update scripts to *ask* `update.nix` to create Git commits.
1033
1034 When support of this feature is declared, whenever the update script exits with `0` return status, it is expected to print a JSON list containing an object described below for each updated attribute to standard output.
1035 Example:
1036
1037 ```json
1038 [
1039 {
1040 "attrPath": "volume_key",
1041 "oldVersion": "0.3.11",
1042 "newVersion": "0.3.12",
1043 "files": [
1044 "/path/to/nixpkgs/pkgs/development/libraries/volume-key/default.nix"
1045 ]
1046 }
1047 ]
1048 ```
1049 :::
1050
1051 When `update.nix` is run with `--argstr commit true`, it will create a separate commit for each of the objects.
1052 An empty list can be returned when the script did not update any files; for example, when the package is already at the latest version.
1053
1054 The commit object contains the following values:
1055
1056 - `attrPath` – a string containing the attribute path
1057 - `oldVersion` – a string containing the old version
1058 - `newVersion` – a string containing the new version
1059 - `files` – a non-empty list of file paths (as strings) to add to the commit
1060 - `commitBody` (optional) – a string with extra content to be appended to the default commit message (useful for adding changelog links)
1061 - `commitMessage` (optional) – a string to use instead of the default commit message
1062
1063 If the returned list contains exactly one object (e.g. `[{}]`), all values are optional and will be determined automatically.
1064
1065## Reviewing contributions
1066
1067### Package updates
1068
1069A package update is the most trivial and common type of pull request.
1070These pull requests mainly consist of updating the version part of the package name and the source hash.
1071
1072It can happen that non-trivial updates include patches or more complex changes.
1073
1074Reviewing process:
1075
1076- Ensure that the package versioning [fits the guidelines](#versioning).
1077- Ensure that the commit text [fits the guidelines](../CONTRIBUTING.md#commit-conventions).
1078- Ensure that the package maintainers are notified.
1079 - The continuous integration system will make GitHub notify users based on the submitted changes, but it can happen that it misses some of the package maintainers.
1080- Ensure that the meta field information [fits the guidelines](#meta-attributes) and is correct:
1081 - License can change with version updates, so it should be checked to match the upstream license.
1082 - If the package has no maintainer, a maintainer must be set.
1083 This can be the update submitter or a community member that accepts to take maintainership of the package.
1084- Verify any change of upstream.
1085 - If switching from e.g. PyPi to GitHub, verify that the repo is the official one.
1086 - If switching to a fork, check with external sources like other package repositories for community consensus.
1087- Ensure any special packaging choices and required context are documented in i.e. the name of a patch or in a comment.
1088 - If a special version of a package is pinned, document why, so others know if/when it can be unpinned.
1089 - If any (especially opinionated) patch or `substituteInPlace` is applied, document why.
1090 - If any non-default build flags are set, document why.
1091 - If checks are partially or fully disabled, document why.
1092- Ensure that the code contains no typos.
1093- Build the package locally.
1094 - Pull requests are often targeted to the master or staging branch, and building the pull request locally when it is submitted can trigger many source builds.
1095 - It is possible to rebase the changes on nixos-unstable or nixpkgs-unstable for easier review by running the following commands from a nixpkgs clone.
1096
1097 ```ShellSession
1098 $ git fetch origin nixos-unstable
1099 $ git fetch origin pull/PRNUMBER/head
1100 $ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD
1101 ```
1102
1103 - The first command fetches the nixos-unstable branch.
1104 - The second command fetches the pull request changes, `PRNUMBER` is the number at the end of the pull request title and `BASEBRANCH` the base branch of the pull request.
1105 - The third command rebases the pull request changes to the nixos-unstable branch.
1106 - The [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) tool can be used to review a pull request content in a single command.
1107 `PRNUMBER` should be replaced by the number at the end of the pull request title.
1108 You can also provide the full github pull request url.
1109
1110 ```ShellSession
1111 $ nix-shell -p nixpkgs-review --run "nixpkgs-review pr PRNUMBER"
1112 ```
1113- Run every binary.
1114
1115Sample template for a package update review is provided below.
1116
1117```markdown
1118##### Reviewed points
1119
1120- [ ] package name fits guidelines
1121- [ ] package version fits guidelines
1122- [ ] package builds on ARCHITECTURE
1123- [ ] executables tested on ARCHITECTURE
1124- [ ] any change of upstream are verified
1125- [ ] the motives for any special packaging choices are documented
1126- [ ] all depending packages build
1127- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
1128- [ ] patches that are remotely available are fetched rather than vendored
1129
1130##### Possible improvements
1131
1132##### Comments
1133```
1134
1135### New packages
1136
1137New packages are a common type of pull requests.
1138These pull requests consist in adding a new nix-expression for a package.
1139
1140Review process:
1141
1142- Ensure that all file paths [fit the guidelines](../CONTRIBUTING.md#file-naming-and-organisation).
1143- Ensure that the package name and version [fits the guidelines](#package-naming).
1144- Ensure that the package versioning [fits the guidelines](#versioning).
1145- Ensure that the commit text [fits the guidelines](../CONTRIBUTING.md#commit-conventions).
1146- Ensure that the source is fetched from an official location, one of our [trusted mirrors](./build-support/fetchurl/mirrors.nix), or a mirror trusted by the authors.
1147- Ensure that the meta fields [fits the guidelines](#meta-attributes) and contain the correct information:
1148 - License must match the upstream license.
1149 - Platforms should be set (or the package will not get binary substitutes).
1150 - Maintainers must be set.
1151 This can be the package submitter or a community member that accepts taking up maintainership of the package.
1152 - The `meta.mainProgram` must be set if a main executable exists.
1153- Ensure any special packaging choices and required context are documented in, i.e., the name of a patch or in a comment.
1154 - If a special version of a package is pinned, document why, so others know if/when it can be unpinned.
1155 - If any (especially opinionated) patch or `substituteInPlace` is applied, document why.
1156 - If any non-default build flags are set, document why.
1157 - If checks are partially or fully disabled, document why.
1158- Report detected typos.
1159- Ensure the package source:
1160 - Uses `mirror://` URLs when available.
1161 - Uses the most appropriate functions (e.g. packages from GitHub should use `fetchFromGitHub`).
1162- Build the package locally.
1163- Run every binary.
1164
1165Sample template for a new package review is provided below.
1166
1167```markdown
1168##### Reviewed points
1169
1170- [ ] package path fits guidelines
1171- [ ] package name fits guidelines
1172- [ ] package version fits guidelines
1173- [ ] package builds on ARCHITECTURE
1174- [ ] executables tested on ARCHITECTURE
1175- [ ] `meta.description` is set and fits guidelines
1176- [ ] `meta.license` fits upstream license
1177- [ ] `meta.platforms` is set
1178- [ ] `meta.maintainers` is set
1179- [ ] `meta.mainProgram` is set, if applicable.
1180- [ ] build time only dependencies are declared in `nativeBuildInputs`
1181- [ ] source is fetched from an official or trusted location
1182- [ ] source is fetched using the appropriate function
1183- [ ] the motives for any special packaging choices are documented
1184- [ ] the list of `phases` is not overridden
1185- [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`.
1186- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
1187- [ ] patches that are remotely available are fetched rather than vendored
1188
1189##### Possible improvements
1190
1191##### Comments
1192```
1193
1194## Security
1195
1196### Submitting security fixes
1197[security-fixes]: #submitting-security-fixes
1198
1199Security fixes are submitted in the same way as other changes and thus the same guidelines apply.
1200
1201- If a new version fixing the vulnerability has been released, update the package;
1202- 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.
1203 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.:
1204
1205 ```nix
1206 (fetchpatch {
1207 name = "CVE-2019-11068.patch";
1208 url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
1209 hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";
1210 })
1211 ```
1212
1213If 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.
1214
1215Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`.
1216
1217### Vulnerability Roundup
1218
1219#### Issues
1220
1221Vulnerable packages in Nixpkgs are managed using issues.
1222Currently opened ones can be found using the following:
1223
1224[github.com/NixOS/nixpkgs/issues?q=is:issue+is:open+"Vulnerability+roundup"](https://github.com/NixOS/nixpkgs/issues?q=is%3Aissue+is%3Aopen+%22Vulnerability+roundup%22)
1225
1226Each issue corresponds to a vulnerable version of a package; as a consequence:
1227
1228- One issue can contain several CVEs;
1229- One CVE can be shared across several issues;
1230- A single package can be concerned by several issues.
1231
1232
1233A "Vulnerability roundup" issue usually respects the following format:
1234
1235```txt
1236<link to relevant package search on search.nix.gsc.io>, <link to relevant files in Nixpkgs on GitHub>
1237
1238<list of related CVEs, their CVSS score, and the impacted NixOS version>
1239
1240<list of the scanned Nixpkgs versions>
1241
1242<list of relevant contributors>
1243```
1244
1245Note that there can be an extra comment containing links to previously reported (and still open) issues for the same package.
1246
1247
1248#### Triaging and Fixing
1249
1250**Note**: An issue can be a "false positive" (i.e. automatically opened, but without the package it refers to being actually vulnerable).
1251If you find such a "false positive", comment on the issue an explanation of why it falls into this category, linking as much information as the necessary to help maintainers double check.
1252
1253If you are investigating a "true positive":
1254
1255- Find the earliest patched version or a code patch in the CVE details;
1256- Is the issue already patched (version up-to-date or patch applied manually) in Nixpkgs's `master` branch?
1257 - **No**:
1258 - [Submit a security fix][security-fixes];
1259 - Once the fix is merged into `master`, [submit the change to the vulnerable release branch(es)](../CONTRIBUTING.md#how-to-backport-pull-requests);
1260 - **Yes**: [Backport the change to the vulnerable release branch(es)](../CONTRIBUTING.md#how-to-backport-pull-requests).
1261- When the patch has made it into all the relevant branches (`master`, and the vulnerable releases), close the relevant issue(s).