maintainers/README.md

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