From 0bd8c9b4f9e2af62795dfbc257aa63bcb89e33e8 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 14 Aug 2023 02:11:50 +0200 Subject: [PATCH] CONTRIBUTING.md: New section on which branch to use --- CONTRIBUTING.md | 81 ++++++++++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5706acd153b..9876d4d9e6b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ This section describes in some detail how changes can be made and proposed with - The name of the branch hints at the change you'd like to implement, e.g. `update-hello`. - The base of the branch includes the most recent changes on the `master` branch. > **Note** - > Depending on the change you may want to use a different branch, see + > Depending on the change you may want to use a different branch, see [][branch]. ```bash # Make sure you have the latest changes from upstream Nixpkgs @@ -106,6 +106,54 @@ This section describes in some detail how changes can be made and proposed with git push --force-with-lease ``` +### Which branch to use +[branch]: #which-branch-to-use + +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](#backporting-changes). + - No: Create separate pull requests to the `master` and `release-XX.YY` branches. + +Furthermore, if the change causes a [mass rebuild][mass-rebuilds], 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 [staging](#staging) for more details about such changes propagate between the branches. + +#### Changes acceptable for releases +[release-acceptable]: #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 not receive any breaking changes, both for the Nix expressions and derivations. +So these changes are acceptable 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 +[mass-rebuilds]: #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). + ### Rebasing between branches (i.e. from master to staging) From time to time, changes between branches must be rebased, for example, if the @@ -197,29 +245,7 @@ So e.g. the [`nixpkgs-unstable` branch](https://github.com/nixos/nixpkgs/tree/ni Nixpkgs in its entirety is tied to the NixOS release process, which is documented in the [NixOS Release Wiki](https://nixos.github.io/release-wiki/). -Changes should generally always go to the `master` branch. -Once in `master`, it can be backported to the `release-YY.MM` branches if [acceptable](#acceptable-backport-criteria). -A change should only go to the `release-YY.MM` branch directly if `master` doesn't need that change. - -#### Acceptable backport criteria - -Backports are only accepted to supported releases. -The oldest supported release (`YYMM`) can be found using -``` -nix-instantiate --eval -A lib.trivial.oldestSupportedRelease -``` - -The release branches should generally not receive any breaking changes, both for the Nix expressions and derivations. -So these changes are acceptable 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` +See [this section][branch] to know when to use the release branches. #### Backporting changes @@ -340,13 +366,6 @@ The staging workflow is used for all main branches, `master` and `release-YY.MM` - `staging`/`staging-YY.MM` - `staging-next`/`staging-next-YY.MM` -#### 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). - ## Reviewing contributions > **Warning**