Nixpkgs Contribution Guidelines: Mass Rebuilds, Commit, and Review Conventions

- Mass rebuilds to `release-YY.MM` should go to `staging-YY.MM` instead. See [this section][staging] for how such changes propagate between the branches. ### Changes acceptable for releases Only changes to _supported_ releases may be accepted. The oldest supported release (`YYMM`) can be found using ``` nix-instantiate --eval -A lib.trivial.oldestSupportedRelease ``` The release branches should generally only receive backwards-compatible changes, both for the Nix expressions and derivations. Here are some examples of changes that are okay to backport: - ✔️ New packages, modules and functions - ✔️ Security fixes - ✔️ Package version updates - ✔️ Patch versions with fixes - ✔️ Minor versions with new functionality, but no breaking changes In addition, major package version updates with breaking changes are also acceptable for: - ✔️ Services that would fail without up-to-date client software, such as `spotify`, `steam`, and `discord` - ✔️ Security critical applications, such as `firefox` and `chromium` ### Changes causing mass rebuilds Which changes cause mass rebuilds is not formally defined. In order to help the decision, CI automatically assigns [`rebuild` labels](https://github.com/NixOS/nixpkgs/labels?q=rebuild) to pull requests based on the number of packages they cause rebuilds for. As a rule of thumb, if the number of rebuilds is **500 or more**, consider targeting the `staging` branch instead of `master`; if the number is **1000 or more**, the pull request causes a mass rebuild, and should target the `staging` branch. See [previously merged pull requests to the staging branches](https://github.com/NixOS/nixpkgs/issues?q=base%3Astaging+-base%3Astaging-next+is%3Amerged) to get a sense for what changes are considered mass rebuilds. ## Commit conventions - Create one commit for each logical unit. - If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`. See [Squashing Commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) for additional information. - For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message). - When adding yourself to `maintainer-list.nix`, make a separate commit with the message `maintainers: add <handle>`. Add the commit before those making changes to the package or module. See [Nixpkgs Maintainers](./maintainers/README.md) for details. - Make sure you read about any commit conventions specific to the area you're touching. See: - [Commit conventions](./doc/README.md#commit-conventions) for changes to `doc`, the Nixpkgs manual. - [Commit conventions](./lib/README.md#commit-conventions) for changes to `lib`. - [Commit conventions](./nixos/README.md#commit-conventions) for changes to `nixos`. - [Commit conventions](./pkgs/README.md#commit-conventions) for changes to `pkgs`. ### Writing good commit messages It's important to include relevant information in the *commit message*, so others can later understand *why* a change was made. While this potentially can be understood by reading code, PR discussion or upstream changes, doing so often requires a lot of work. Simple package version updates need to include the attribute name, old and new versions, as well as a reference to the release notes or changelog. Package upgrades with more extensive changes require more verbose commit messages. ## Review and Merge conventions Comments on Pull Requests are considered non-blocking by default. Every blocking comment must be explicitly marked as such by using GitHub's "Request Changes" review type. A reviewer who submits a blocking review should be available for discussion and re-review. An abandoned review may be dismissed after reasonable time was given at the discretion of the merger. All suggestions for change, blocking or not, should be acknowledged before merge. This can happen implicitly by applying the suggestion, or explicitly by rejecting it.

This chunk details further contribution guidelines for Nixpkgs. It specifies that 'mass rebuilds' (defined as changes causing 500+ rebuilds, or definitively 1000+) should target `staging` or `staging-YY.MM` branches instead of `master`. It then outlines commit conventions, including using one commit per logical unit, squashing fixup commits, avoiding periods in summary lines, and using a specific format for adding maintainers. Emphasis is placed on writing informative commit messages that explain the 'why' behind changes, especially for package version updates. Finally, it covers pull request review conventions: comments are non-blocking by default unless explicitly marked as 'Request Changes', and all suggestions must be acknowledged before a merge.