diff --git a/MAINTAINING.md b/MAINTAINING.md index 0911abb3..8a8edbcb 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -27,12 +27,12 @@ If a warning is created on release `n`, then: Nixvim releases stable versions in sync with nixpkgs. A _`YY.05`_ version is released in May and a _`YY.11`_ version is released in November. +A new release branch can be created at any point during the Nixpkgs branch-off period. We do not need to wait for the release to come out of _“beta”_ before creating a branch, however we _should_ wait before updating links and references on the `main` branch. - -Creating a stable branch may require temporarily disabling branch protection. This can only be done by an "admin" or "owner". +See [Creating the release branch](#creating-the-release-branch) below. Once a stable branch is created, its flake inputs should be updated to point to the corresponding stable versions. -The branch can be created before these exist, in which case they should be updated when the corresponding stable inputs become available. +See [Pinning the release branch's inputs](#pinning-the-release-branch-inputs). Once a stable version is considered "out of beta", references to Nixvim's stable branch should be updated on the `main` branch to reference the new version. @@ -42,3 +42,34 @@ The `update` workflow will automatically add info about stable branches to `vers This is used by CI workflows like `update-other` and `website` to automatically list supported stable versions. This should usually be handled automatically, however errors may show up if a version is added to `version-info.toml` before the corresponding Nixvim branch exists. + +### Creating the release branch + +Currently, anyone with write access can create new branches. +A branch can be created using GitHub's [web UI](https://github.com/nix-community/nixvim/branches) or by pushing to `upstream` using the `git` CLI. + +The branch should be named `nixos-YY.MM` (replacing `YY.MM` with the actual release version), corresponding with the targeted Nixpkgs release. + +Ideally, the new branch should be created before `main` is bumped onto the next unstable release. +Otherwise, the new branch can be created at an earlier commit in `main`'s history, from before the bump. + +> [!IMPORTANT] +> Currently, GitHub Rulesets enabling Merge Queue cannot target a branch pattern. +> Therefore, we must manually add the new `nixos-YY.MM` branch to our [Merge Queues ruleset](https://github.com/nix-community/nixvim/settings/rules/17034101). + +If the branch naming scheme is ever changed, we must update any GitHub Rulesets targeting the `nixos-*` branch pattern. + +### Pinning the release branch inputs + +Once a stable branch is created, its flake inputs should be updated to point to the corresponding stable versions. +This is typically done in a PR targeting the new release branch, after the branch has been created. +If release-specific URLs do not exist immediately, they can be left untouched. +Follow-up PRs should update to pinned-URLs as they become available. + +## Archiving + +Once a release is no longer maintained, it can be added to the [Archived branches ruleset](https://github.com/nix-community/nixvim/settings/rules/17034875) and removed from the [Merge Queues ruleset](https://github.com/nix-community/nixvim/settings/rules/17034101). +This will block pushing to those branches, even via PRs. + +We have not discussed whether an archival notice should be added to unmaintained branch READMEs, +or whether evaluating unmaintained branches should print a warning.