CONTRIBUTING.md: New section on which branch to use
This commit is contained in:
parent
2a99b5a703
commit
0bd8c9b4f9
1 changed files with 50 additions and 31 deletions
|
@ -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 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.
|
- The base of the branch includes the most recent changes on the `master` branch.
|
||||||
> **Note**
|
> **Note**
|
||||||
> Depending on the change you may want to use a different branch, see <!-- TODO link to branch section -->
|
> Depending on the change you may want to use a different branch, see [][branch].
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Make sure you have the latest changes from upstream Nixpkgs
|
# 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
|
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)
|
### Rebasing between branches (i.e. from master to staging)
|
||||||
|
|
||||||
From time to time, changes between branches must be rebased, for example, if the
|
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/).
|
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.
|
See [this section][branch] to know when to use the release branches.
|
||||||
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`
|
|
||||||
|
|
||||||
#### Backporting changes
|
#### 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`/`staging-YY.MM`
|
||||||
- `staging-next`/`staging-next-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
|
## Reviewing contributions
|
||||||
|
|
||||||
> **Warning**
|
> **Warning**
|
||||||
|
|
Loading…
Reference in a new issue