Home • Explore • Blog • Models • CI
☰



nixpkgs
8th chunk of `CONTRIBUTING.md`
700c3715b12ae8c479b14d22d5d7c34fad7b41755993199d0000000100000ffb
This is implemented using GitHub workflows [here](.github/workflows/periodic-merge-6h.yml) and [here](.github/workflows/periodic-merge-24h.yml).

> [!Note]
> Changes must be well tested before being merged into any branch.
> Hydra builds should not be used as a testing platform.

Here is a Git history diagram showing the flow of commits between the three branches:
```mermaid
%%{init: {
    'theme': 'base',
    'themeVariables': {
        'gitInv0': '#ff0000',
        'gitInv1': '#ff0000',
        'git2': '#ff4444',
        'commitLabelFontSize': '15px'
    },
    'gitGraph': {
        'showCommitLabel':true,
        'mainBranchName': 'master',
        'rotateCommitLabel': true
    }
} }%%
gitGraph
    commit id:" "
    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 stable branches with corresponding names:
- `master`/`release-YY.MM`
- `staging`/`staging-YY.MM`
- `staging-next`/`staging-next-YY.MM`

# Conventions

## Branch conventions
<!-- This section is relevant to both contributors and reviewers -->

Most changes should go to `master`, but sometimes other branches should be used instead.
Use the following decision process to figure out the right branch:

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 package's 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-YY.MM` branches.

If the change causes a [mass rebuild][mass-rebuild], use the `staging` branch instead:
- Mass rebuilds to `master` should go to `staging` instead.
- 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
Title: Nixpkgs Branching Strategy, Staging Workflow Details, and Release Conventions
Summary
This chunk details the Nixpkgs branching strategy, presenting a Git history diagram and a table outlining the roles of `master`, `staging-next`, and `staging` branches. `master` is for general development and built by Hydra; `staging-next` handles Hydra builds and fixes for mass-rebuild changes; `staging` is where mass-rebuild changes are developed. The workflow involves periodic automatic merges (master -> staging-next -> staging) and manual merges (staging -> staging-next -> master). It then provides conventions for branch selection: `master` for most changes, but `staging` (or `staging-YY.MM` for releases) for mass-rebuilds. The document also defines 'acceptable for releases' changes, generally favoring backwards-compatible updates, security fixes, and new features, with allowances for major version updates in critical applications like browsers or essential services.