Nixpkgs Branch Conventions and Mass Rebuilds

branch staging commit id:" " branch staging-next merge master id:"automatic" checkout staging merge staging-next id:"automatic " checkout staging-next merge staging type:HIGHLIGHT id:"manual" commit id:"fixup" checkout master checkout staging checkout master commit id:" " checkout staging-next merge master id:"automatic " checkout staging merge staging-next id:"automatic " checkout staging-next commit id:"fixup " checkout master merge staging-next type:HIGHLIGHT id:"manual (PR)" ``` Here's an overview of the different branches: | branch | `master` | `staging-next` | `staging` | | --- | --- | --- | --- | | Used for development | ✔️ | ❌ | ✔️ | | Built by Hydra | ✔️ | ✔️ | ❌ | | [Mass rebuilds][mass-rebuild] | ❌ | ⚠️ Only to fix Hydra builds | ✔️ | | Critical security fixes | ✔️ for non-mass-rebuilds | ✔️ for mass-rebuilds | ❌ | | Automatically merged into | `staging-next` | `staging` | - | | Manually merged into | - | `master` | `staging-next` | The staging workflow is used for all main branches, `master` and `release-YY.MM`, with corresponding names: - `master`/`release-YY.MM` - `staging`/`staging-YY.MM` - `staging-next`/`staging-next-YY.MM` # Conventions ## Branch conventions  Most changes should go to the `master` branch, but sometimes other branches should be used instead. Use the following decision process to figure out which one it should be: Is the change [acceptable for releases][release-acceptable] and do you wish to have the change in the release? - No: Use the `master` branch, do not backport the pull request. - Yes: Can the change be implemented the same way on the `master` and release branches? For example, a packages major version might differ between the `master` and release branches, such that separate security patches are required. - Yes: Use the `master` branch and [backport the pull request](#how-to-backport-pull-requests). - No: Create separate pull requests to the `master` and `release-XX.YY` branches. Furthermore, if the change causes a [mass rebuild][mass-rebuild], use the appropriate staging branch instead: - Mass rebuilds to `master` should go to `staging` instead. - Mass rebuilds to `release-XX.YY` should go to `staging-XX.YY` instead. See [this section][staging] for more details about 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 backwards-compatible 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 **over 500**, it can be considered a mass rebuild. To get a sense for what changes are considered mass rebuilds, see [previously merged pull requests to the staging branches](https://github.com/NixOS/nixpkgs/issues?q=base%3Astaging+-base%3Astaging-next+is%3Amerged). ## Commit conventions

This section details the branch conventions used in Nixpkgs, expanding on the roles of `master`, `staging`, and `staging-next` branches. It clarifies when to use each branch based on whether a change is acceptable for releases, can be implemented the same way across branches, and whether it causes a mass rebuild. Changes that are acceptable for release, are backported, while those causing mass rebuilds go to `staging` or `staging-YY.MM`. Acceptable changes include new packages, security fixes, and package version updates. A change is considered a mass rebuild if it affects more than 500 packages. It outlines commit conventions.