From e3f8406683ecbc30594fdfeb29552b13cbf1e40c Mon Sep 17 00:00:00 2001 From: Austin Horstman Date: Wed, 26 Nov 2025 09:50:09 -0600 Subject: [PATCH] maintaining.md: add maintaining document Outline the places we need to update for releases and how we handle certain things. Signed-off-by: Austin Horstman --- MAINTAINING.md | 208 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 MAINTAINING.md diff --git a/MAINTAINING.md b/MAINTAINING.md new file mode 100644 index 000000000..41adbc41d --- /dev/null +++ b/MAINTAINING.md @@ -0,0 +1,208 @@ +# Maintaining Home Manager + +This file is intended as a reference for Home Manager's core maintainers, +although it may be interesting for anyone curious how we do certain things. + +## Releasing + +Home Manager releases stable versions in sync with NixOS/nixpkgs. A _`YY.05`_ +version is released in May and a _`YY.11`_ version is released in November. + +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 +`master` branch. + +Creating a stable branch may require temporarily disabling branch protection. +This can only be done by an "admin" or "owner". + +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. + +Once a stable version is considered "out of beta", references to Home Manager's +stable branch should be updated on the `master` branch to reference the new +version. + +### Release Workflow + +The release process involves four phases in a specific order: + +1. **On master - Mark current as stable**: Update all documentation and examples + to reflect the current release (e.g., 25.11) as stable, removing "(unstable)" + tags +2. **Cut the release branch**: Create the new release branch from master (e.g., + `release-25.11`) +3. **On release branch - Mark as release branch**: Set `isReleaseBranch: true` + in `release.json` +4. **On master - Prepare for next**: Bump version to next release (e.g., 26.05) + and add "(unstable)" tag back + +**Important**: The `isReleaseBranch` field in `release.json` is managed +differently on each branch: + +- On **master**: Always remains `false` +- On **release branches**: Set to `true` in a separate commit after cutting the + branch from master + +This workflow ensures that the release branch captures a stable snapshot of +master, which then moves forward to the next development cycle. + +### Release Preparation Checklist + +#### Step 1: On master - Mark Current as Stable + +**When**: When ready to cut a new release branch (e.g., when preparing to +release 25.11) + +Reference commits: + +- `e08e6e2389234000b0447e57abf61d8ccd59a68e` (home-manager: set 25.05 as stable) + +1. **README.md** + - Update example release branch references (e.g., `release-24.11` → + `release-25.05`) + - Update current stable version references (e.g., `24.11` → `25.05`) + +2. **docs/manual/installation/nix-darwin.md** + - Update channel version in example commands + - Update `home.stateVersion` in examples + +3. **docs/manual/installation/nixos.md** + - Update channel version in example commands + - Update tarball URLs + - Update `home.stateVersion` in examples + +4. **docs/manual/installation/standalone.md** + - Update channel version in example commands + +5. **docs/manual/manual.md** + - Remove `(unstable)` suffix from version + +6. **docs/manual/nix-flakes/standalone.md** + - Update flake references (e.g., `home-manager/release-24.11` → + `home-manager/release-25.05`) + - Update `$branch` examples + +7. **docs/manual/usage/configuration.md** + - Update `home.stateVersion` in example configurations + +8. **docs/release-notes/rl-YYMM.md** + - Replace "This is the current unstable branch and the information in this + section is therefore not final." + - With: "The YY.MM release branch became stable in , YYYY." + +9. **home-manager/home-manager** script + - Update default `home.stateVersion` in generated configurations + - Update `home.stateVersion` in uninstall function + +10. **modules/misc/uninstall.nix** + - Update `home.stateVersion` in uninstall config + +**Note**: Do NOT change `isReleaseBranch` in `release.json` - keep it as `false` + +#### Step 2: Cut the release branch + +**When**: After Step 1 is merged to master + +1. Create the new release branch from master + - Example: `git checkout -b release-25.11 master` +2. Push the branch to the repository + +#### Step 3: On the release branch - Mark as Release Branch + +**When**: Immediately after creating the release branch + +Reference commits: + +- `70a787cc5` (release: set release branch) + +1. **release.json** + - Change `isReleaseBranch` from `false` to `true` + - Do NOT change the `release` field (it's already correct from Step 1) + +#### Step 3.5: On master - Update CI for the New Release Branch + +**When**: After marking the release branch as a release branch (Step 3) + +**Where**: On the **master** branch (CI workflows run from master) + +**What**: Update GitHub Actions workflows to include the new stable branch + +1. **.github/workflows/update-flake.yml** (on master) + - Replace the old stable branch with the new release branch in the matrix + - Example: When creating `release-25.11`, update the matrix from: + + ```yaml + strategy: + matrix: + branch: [master, release-25.05] + ``` + + to: + + ```yaml + strategy: + matrix: + branch: [master, release-25.11] + ``` + + - This ensures automated flake.lock updates run on the current stable branch + - Note: We only maintain CI for the latest stable release, not older releases + +**Important**: CI workflows are executed from master, so this change must be +committed to the master branch. + +#### Step 4: On master - Prepare for Next Release + +**When**: After cutting the release branch, prepare master for the next +development cycle + +Reference commits: + +- `9a4a9f1d6e43fe4044f6715ae7cc85ccb1d2fe09` (home-manager: prepare 25.11) + +1. **docs/release-notes/rl-YYMM.md** (CREATE NEW) + - Create new release notes file for next version with unstable warning + - Example: Create `rl-2605.md` when preparing for 26.05 + +2. **docs/manual/manual.md** + - Update version to next release with `(unstable)` tag + - Example: `25.11` → `26.05 (unstable)` + +3. **docs/release-notes/release-notes.md** + - Add new release notes file `rl-YYMM.md` at the top of the chapters list + +4. **home-manager/home-manager** script + - Update `--version` output to next version + - Example: `echo 25.11-pre` → `echo 26.05-pre` + +5. **modules/misc/version.nix** + - Add new version string to `stateVersion` enum list + - Example: Add `"26.05"` after `"25.11"` + +6. **release.json** + - Update `release` field to next version (e.g., `"25.11"` → `"26.05"`) + - **IMPORTANT**: Keep `isReleaseBranch` as `false` on master + +### Version State Changes + +Each release may introduce state version changes that affect the default +behavior of Home Manager for users who set `home.stateVersion` to that version. + +State version changes should be documented in the release notes under a "State +Version Changes" section, explaining what behavior changes for users who set +their state version to the new release. + +### Backporting + +Stable branches get bug fixes and security updates, but usually not new modules +or features. When backporting: + +1. Use `git cherry-pick -x ` to preserve the original commit reference +2. Test that the backport builds successfully +3. Consider whether the change might affect existing stable users +4. Update the PR/commit message to indicate it's a backport + +If a user needs a module backported, they should open an issue explaining the +use case.