pyrox.dev
1# Nixpkgs Maintainers
2
3Unlike other packaging ecosystems, the maintainer doesn't have exclusive control over the packages and modules they maintain.
4This more fluid approach is one reason why we scale to so many packages.
5
6## Definition and role of the maintainer
7
8The main responsibility of a maintainer is to keep the packages they maintain in a functioning state, and keep up with updates.
9In order to do that, they are empowered to make decisions over the packages they maintain.
10
11That being said, the maintainer is not alone proposing changes to the packages.
12Anybody (both bots and humans) can send PRs to bump or tweak the package.
13
14We also allow other non-maintainer committers to merge changes to the package, provided enough time and priority has been given to the maintainer.
15
16For most packages, we expect committers to wait at least a week before merging changes not endorsed by a package maintainer (which may be themselves).
17This should leave enough time for the maintainers to provide feedback.
18
19For critical packages, this convention needs to be negotiated with the maintainer.
20A critical package is one that causes mass-rebuild, or where an author is listed in the [`OWNERS`](../ci/OWNERS) file.
21
22In case of critical security updates, the [security team](https://nixos.org/community/teams/security) might override these heuristics in order to get the fixes in as fast as possible.
23
24In case of conflict, the maintainer takes priority and is allowed to revert the changes.
25This can happen for example if the maintainer was on holiday.
26
27### How to become a maintainer
28
29We encourage people who care about a package to assign themselves as a maintainer.
30Commit access to the Nixpkgs repository is not required for that.
31
32In order to do so, add yourself to the [`maintainer-list.nix`](./maintainer-list.nix), and then to the desired package's `meta.maintainers` list, and send a PR with the changes.
33
34If you're adding yourself as a maintainer as part of another PR (in which you become a maintainer of a package, for example), make your change to
35`maintainer-list.nix` in a separate commit titled `maintainers: add <name>`.
36
37### Losing maintainer status
38
39Maintainers who have become inactive can be removed.
40This helps us keep an accurate view of the state of maintenance in Nixpkgs.
41
42The inactivity measure is currently not strictly enforced.
43We would typically look at it if we notice that the author hasn't reacted to package-related notifications for more than 3 months.
44
45Removing the maintainer happens by making a PR, adding that person as a reviewer, and then waiting a week for a reaction.
46
47The maintainer is welcome to come back at any time.
48
49## Tools for maintainers
50
51When a pull request is made against a package, nixpkgs CI will notify the appropriate maintainer(s) by trying to correlate the files the PR touches with the packages that need rebuilding.
52This process is subject to error however, so we encourage PR authors to notify the appropriate people.
53
54Maintainers can also invoke the [nixpkgs-merge-bot](https://github.com/nixos/nixpkgs-merge-bot) to merge pull requests targeting packages they are the maintainer of, which satisfy the current security [constraints](https://github.com/NixOS/nixpkgs-merge-bot/blob/main/README.md#constraints).
55Examples: [#397273](https://github.com/NixOS/nixpkgs/pull/397273#issuecomment-2789382120) and [#377027](https://github.com/NixOS/nixpkgs/pull/377027#issuecomment-2614510869)
56
57New maintainers will automatically get invited to join the [NixOS/nixpkgs-maintainers](https://github.com/orgs/NixOS/teams/nixpkgs-maintainers) GitHub team.
58By joining, you will get some triaging rights in the nixpkgs repository, like the ability to close and reopen issues made by others, and managing labels.
59However, the GitHub team invite is usually only sent by email, and is only valid for one week!
60Should it expire, please ask for a re-invite in the [GitHub org owners help desk Matrix channel](https://matrix.to/#/#org_owners:nixos.org).
61
62### Unofficial maintainer tooling
63
64[zh.fail](https://zh.fail/failed/overview.html) tracks all package build failures on `master` grouped by maintainer.
65
66[asymmetric/nixpkgs-update-notifier](https://github.com/asymmetric/nixpkgs-update-notifier) is a matrix bot that scrapes the [nixpkgs-update logs](https://nixpkgs-update-logs.nix-community.org/) and notifies you if nixpkgs-update/@r-ryantm fails to update any of the packages you've subscribed to.
67
68[repology.org](https://repology.org) tracks and compares the versions of packages between various package repositories, letting you know what packages may be out of date or insecure.
69You can view which packages a specific maintainer maintains and subscribe to updates with atom/rss.
70Example: [repology.org/maintainer/pbsds](https://repology.org/maintainer/pbsds%40hotmail.com).
71
72[nixpk.gs/pr-tracker](https://nixpk.gs/pr-tracker.html) and [nixpkgs-tracker.ocfox.me](https://nixpkgs-tracker.ocfox.me/) can visualize the release status of any nixpkgs pull request.
73
74## Reviewing contributions
75
76### Individual maintainer list
77
78When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the following checks should be performed:
79
80- If the user has specified a GPG key, verify that the commit is signed by their key.
81
82 First, validate that the commit adding the maintainer is signed by the key the maintainer listed.
83 Check out the pull request and compare its signing key with the listed key in the commit.
84
85 If the commit is not signed or it is signed by a different user, ask them to either recommit using that key or to remove their key information.
86
87 Given a maintainer entry like this:
88
89 ```nix
90 {
91 example = {
92 email = "user@example.com";
93 name = "Example User";
94 keys = [ { fingerprint = "0000 0000 2A70 6423 0AED 3C11 F04F 7A19 AAA6 3AFE"; } ];
95 };
96 }
97 ```
98
99 First receive their key from a keyserver:
100
101 $ gpg --recv-keys 0xF04F7A19AAA63AFE
102 gpg: key 0xF04F7A19AAA63AFE: public key "Example <user@example.com>" imported
103 gpg: Total number processed: 1
104 gpg: imported: 1
105
106 Then check the commit is signed by that key:
107
108 $ git log --show-signature
109 commit b87862a4f7d32319b1de428adb6cdbdd3a960153
110 gpg: Signature made Wed Mar 12 13:32:24 2003 +0000
111 gpg: using RSA key 000000002A7064230AED3C11F04F7A19AAA63AFE
112 gpg: Good signature from "Example User <user@example.com>
113 Author: Example User <user@example.com>
114 Date: Wed Mar 12 13:32:24 2003 +0000
115
116 maintainers: adding example
117
118 and validate that there is a `Good signature` and the printed key matches the user's submitted key.
119
120 Note: GitHub's "Verified" label does not display the user's full key fingerprint, and should not be used for validating the key matches.
121
122- Ensure that the user has specified a `github` account name and a `githubId` and verify the two match.
123
124 People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer.
125
126 Given a maintainer entry like this:
127
128 ``` nix
129 {
130 example = {
131 email = "user@example.com";
132 name = "Example User";
133 github = "ghost";
134 githubId = 10137;
135 };
136 }
137 ```
138
139 First, make sure that the listed GitHub handle matches the author of the commit.
140
141 Then, visit the URL `https://api.github.com/user/10137` and validate that the `login` field matches the provided `github` handle.
142
143### Maintainer teams
144
145Feel free to create a new maintainer team in [`team-list.nix`](./team-list.nix) when a group is collectively responsible for a collection of packages.
146Use taste and personal judgement when deciding if a team is warranted.
147
148Teams are allowed to define their own rules about membership.
149
150For example, some teams will represent a business or other group which wants to carefully track its members.
151Other teams may be very open about who can join, and allow anybody to participate.
152
153When reviewing changes to a team, read the team's scope and the context around the member list for indications about the team's membership policy.
154
155In any case, request reviews from the existing team members.
156If the team lists no specific membership policy, feel free to merge changes to the team after giving the existing members a few days to respond.
157
158> [!IMPORTANT]
159> If a team says it is a closed group, do not merge additions to the team without an approval by at least one existing member.
160
161A corresponding GitHub team can be created by any org member.
162When creating the team it should be created with the `nixpkgs-maintainers` team as parent.
163Once approved, the team will have the right privileges to be pinged and requested for review in Nixpkgs.
164
165> [!TIP]
166> The team name should be as short as possible; because it is nested under the maintainers group, no -maintainers suffix is needed.
167
168# Maintainer scripts
169
170Various utility scripts, which are mainly useful for nixpkgs maintainers, are available under `./scripts/`.
171See its [README](./scripts/README.md) for further information.
172
173# nixpkgs-merge-bot
174
175To streamline autoupdates, leverage the nixpkgs-merge-bot by commenting `@NixOS/nixpkgs-merge-bot merge` if the package resides in pkgs-by-name, the commenter is among the package maintainers, and the pull request author is @r-ryantm or a Nixpkgs committer.
176The bot ensures that all ofborg checks, except for darwin, are successfully completed before merging the pull request.
177Should the checks still be underway, the bot patiently waits for ofborg to finish before attempting the merge again.
178
179# Guidelines for Committers
180
181When merging pull requests, care must be taken to reduce impact to the `master` branch.
182If a commit breaks evaluation, it will affect Ofborg evaluation results in other pull requests and block Hydra CI, thus introducing chaos to our workflow.
183
184One approach to avoid merging such problematic changes is to wait for successful Ofborg evaluation.
185Additionally, using tools like [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) can help spot issues early, before Ofborg finishes evaluation.
186
187## Breaking changes
188
189In general breaking changes to `master` and `staging` branches are permitted, as long as they are documented in the release notes.
190Though restrictions might apply towards the end of a NixOS release cycle, due to our feature freeze mechanism.
191This is to avoid large-scale breakages shortly before and during a Zero Hydra Failures (ZHF) campaign.
192These restrictions also intend to decrease the likelihood of a delayed NixOS release.
193The feature freeze period is documented in the announcement of each release schedule.
194
195> These are some example changes and if they are considered a breaking change during a freeze period:
196>
197> - `foo: 1.2.3 -> 1.2.4`:
198> Assuming this package follows semantic versioning and none of its dependent packages fail to build because of this change, it can be safely merged.
199> Otherwise, if it can be confirmed that there is no major change in its functionality or API, but only adding new features or fixing bugs, it can also be merged.
200> - `unmaintained-software: drop`:
201> If this PR removes a leaf package or the removal doesn't otherwise break other packages, it can be merged.
202> - `cool-tool: rename from fancy-tool`:
203> As long as this PR replaces all references to the old attribute name with the new name and adds an alias, it can be merged.
204> - `libpopular: 4.3.2 -> 5.0.0`:
205> If this PR would trigger many rebuilds and/or target `staging`, it should probably be delayed until after the freeze-period is over.
206> Alternatively, if this PR is for a popular package and doesn't cause many rebuilds, it should also be delayed to reduce risk of breakage.
207> If a PR includes important changes, such as security fixes, it should be brought up to release managers.
208> - `nixos/transmission: refactor`:
209> If this PR adjusts the type, default value or effect of options in the NixOS module, so that users must rewrite their configuration to keep the current behavior unchanged, it should not be merged, as we don't have enough time to collect user feedback and avoid possible breakage.
210> However, it should be accepted if the current behavior is considered broken and is fixed by the PR.