From f8a89b9c8761bb47cb08986d0ef1dd345912949f Mon Sep 17 00:00:00 2001 From: Jack O'Sullivan Date: Mon, 3 Aug 2026 23:31:26 +0100 Subject: [PATCH] docs: Add guided nixpkgs upgrade procedure Capture the periodic upgrade of the four nixpkgs channels and home-manager as a repo doc: check for a NixOS stable bump first, rebase the devplayer0 fork against upstream (re-verifying the patch stack against freshly fetched refs), run the update commands, sweep version-gated TODOs, and review the remaining flake inputs. Keep the canonical, agent-agnostic procedure in docs/ and point both AGENTS.md and a thin Claude Code skill at it. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/upgrade-nixpkgs/SKILL.md | 25 +++++ AGENTS.md | 4 +- docs/README.md | 2 + docs/nixpkgs-upgrade.md | 125 ++++++++++++++++++++++++ 4 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/upgrade-nixpkgs/SKILL.md create mode 100644 docs/nixpkgs-upgrade.md diff --git a/.claude/skills/upgrade-nixpkgs/SKILL.md b/.claude/skills/upgrade-nixpkgs/SKILL.md new file mode 100644 index 0000000..1937873 --- /dev/null +++ b/.claude/skills/upgrade-nixpkgs/SKILL.md @@ -0,0 +1,25 @@ +--- +name: upgrade-nixpkgs +description: >- + Upgrade all four nixpkgs channels (unstable, stable, mine, mine-stable) and home-manager for this + flake: check for a NixOS stable bump, rebase the devplayer0 nixpkgs fork against upstream, run the + update commands, sweep version-gated TODOs, and review flake inputs. Use when the user wants to + update/bump nixpkgs, refresh the pins, or do the periodic nixpkgs/home-manager upgrade. +--- + +# Upgrade nixpkgs + +The canonical, agent-agnostic procedure lives in the repo at +[`docs/nixpkgs-upgrade.md`](../../../docs/nixpkgs-upgrade.md). Read it and follow the phases in +order. + +Key reminders (see the doc for the full steps): + +- It is **guided, not automated** — do the mechanical/investigative work but stop at the ⏸ points: + pushing the fork, resolving rebase conflicts, editing the `flake.nix` stable pins, and deleting + version guards. Report and let the user decide. +- **Check the current NixOS stable first** (Phase 1) — the fork's `devplayer0-stable` rebase target + and the `flake.nix` stable pins must agree on one release. +- **Re-verify the patch stack against freshly fetched upstream**, not stale refs — enumerate it with + `git log`, don't assume a remembered list (stale `upstream/*` refs make already-upstreamed commits + masquerade as fork-only patches). diff --git a/AGENTS.md b/AGENTS.md index 29ae9cb..cab078c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,7 +61,9 @@ Common ones: `SSH_AUTH_SOCK= ssh-machine …` (or add `-o IdentityAgent=none` to a raw `ssh`). - `ragenix` — edit age secrets using `.keys/dev.key` as identity (see Secrets). - `repl` — `nix repl .#`. -- `update-nixpkgs` / `update-home-manager` — bump pinned inputs. +- `update-nixpkgs` / `update-home-manager` — bump pinned inputs. For the full periodic upgrade + (rebasing the `devplayer0` nixpkgs fork, stable-release bumps, version-gate sweep, input review) + follow the guided procedure in [`docs/nixpkgs-upgrade.md`](docs/nixpkgs-upgrade.md). Use the narrowest relevant evaluation while iterating: `check-system ` for a box config, `nix eval .#nixfiles.config.nixos.allAssignments --json` for assignment generation, or diff --git a/docs/README.md b/docs/README.md index 252f1d4..115c944 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,8 @@ Not every box fits this pattern, but **colony** and **home** are organised this - [`networking.md`](networking.md) — network assignments, domains, site topologies, router HA, the AS211024 L2 mesh, BGP, WireGuard, Tailscale. - [`deployment.md`](deployment.md) — deploy-rs, devshell commands, secrets workflow, CI. +- [`nixpkgs-upgrade.md`](nixpkgs-upgrade.md) — guided procedure for the periodic upgrade of the four + nixpkgs channels and home-manager (fork rebase, stable bumps, input review). - [`reference/dns.md`](reference/dns.md) — generated forward and reverse DNS record reference. - [`reference/nixos-options.md`](reference/nixos-options.md) — generated per-option reference for the custom `my.*` NixOS modules. diff --git a/docs/nixpkgs-upgrade.md b/docs/nixpkgs-upgrade.md new file mode 100644 index 0000000..25d0fd5 --- /dev/null +++ b/docs/nixpkgs-upgrade.md @@ -0,0 +1,125 @@ +# Upgrading nixpkgs + +Procedure for the periodic upgrade of all four nixpkgs channels (`unstable`, `stable`, `mine`, +`mine-stable`) and home-manager. Written to be followed by a person or any coding agent; a +Claude Code entry point exists at `.claude/skills/upgrade-nixpkgs/` but the steps below are the +canonical source. + +The upgrade is **guided, not automated**: do the mechanical and investigative steps, but stop at +the judgment points (marked ⏸) — pushing the fork, resolving rebase conflicts, editing the +`flake.nix` stable pins, and deleting version guards. Report findings and let the maintainer +decide. Keep a running summary and present it before any push or commit. + +Work the phases in order; skip one only if explicitly scoped to a subset. + +## Setup facts + +- **Fork checkout:** `~/documents/projects/nixpkgs` — remotes `origin` (`devplayer0/nixpkgs`) and + `upstream` (`NixOS/nixpkgs`). Confirm the path exists; if not, ask. +- **Fork branches:** `devplayer0` (tracks `nixos-unstable`) and `devplayer0-stable` (tracks the + current NixOS stable). Each is a small stack of local patches rebased onto upstream. +- **Flake pins** in `flake.nix` (`inputs`): + - `nixpkgs-unstable.url = "nixpkgs/nixos-unstable"` + - `nixpkgs-stable.url = "nixpkgs/nixos-"` (e.g. `nixos-26.05`) + - `nixpkgs-mine.url = "github:devplayer0/nixpkgs/devplayer0"` + - `nixpkgs-mine-stable.url = "github:devplayer0/nixpkgs/devplayer0-stable"` + - `home-manager-unstable.url = "home-manager"` + - `home-manager-stable.url = "home-manager/release-"` +- **Devshell commands:** `update-nixpkgs` = `nix flake update nixpkgs-{unstable,stable,mine,mine-stable}`; + `update-home-manager` = `nix flake update home-manager-{unstable,stable}`. +- **Validation:** prefer `check-system ` and `nix flake check --no-build` over full builds. + +## Phase 1 — Determine the current NixOS stable + +Do this first: everything downstream (the fork's `devplayer0-stable` rebase target, the `flake.nix` +stable pins) has to agree on one NixOS stable release, so establish it up front. + +1. Find the latest NixOS stable release branch — check `git branch -r` on `upstream` for the newest + `release-YY.NN`, or the NixOS release schedule. +2. Compare it to `` in the `flake.nix` `nixpkgs-stable` / `home-manager-stable` URLs. +3. **If they already match** (no new stable): note "stable is current" and carry `` into the + later phases. +4. ⏸ **If a newer stable has cut:** stop and report the coordinated change set before proceeding — + the pieces must all move to the same release together: + - Rebase `devplayer0-stable` onto the new `upstream/release-YY.NN` (Phase 2 uses this target). + - Edit `flake.nix`: `nixpkgs-stable.url` and `home-manager-stable.url` → the new release. + - Bump each system's `stateVersion` / `home.stateVersion` only if the maintainer explicitly + wants to — that is a separate, deliberate decision; never auto-bump. + Don't edit `flake.nix` here without confirmation. + +## Phase 2 — Rebase the nixpkgs fork + +For **both** branches — `devplayer0` onto `upstream/nixos-unstable`, and `devplayer0-stable` onto +`upstream/release-` (the release established in Phase 1): + +1. In `~/documents/projects/nixpkgs`, confirm a clean working tree (`git status`). If dirty, stop + and report — don't stash silently. +2. `git fetch upstream --prune` and `git fetch origin --prune`. If the checkout has been idle a + long time this fetch can be large and slow; let it finish. +3. Enumerate the patch stack before rebasing: + `git log --oneline upstream/nixos-unstable..origin/devplayer0` (and the stable equivalent + against `upstream/release-`). For each commit, check whether it has landed upstream or + been superseded — e.g. `git log --oneline upstream/nixos-unstable -- ` or grep the + upstream tree for the package/option. Note any patch that now looks redundant. +4. Rebase: `git switch devplayer0 && git rebase upstream/nixos-unstable` (and the stable branch + onto `upstream/release-`). + - ⏸ **Conflicts:** stop. Report which patch conflicts and against what upstream change; let the + maintainer resolve, or drop the patch if it has been upstreamed. + - Clean rebase: continue. +5. Summarize: which patches still apply, which are now redundant (candidate to drop), which + conflicted. +6. ⏸ **Push:** only after confirmation. `git push --force-with-lease origin devplayer0 + devplayer0-stable` (force needed — rebase rewrites history). + +## Phase 3 — Update the pinned inputs + +Run together (they move as a set): + +``` +update-nixpkgs +update-home-manager +``` + +Then show the `flake.lock` diff for the nixpkgs/home-manager entries so the old→new revisions are +visible. + +## Phase 4 — Sweep version-gated behavior + +The repo carries branch-conditional logic and TODOs keyed to specific nixpkgs versions; some become +removable after an upgrade, especially after a stable bump. Surface them: + +``` +grep -rn "versionAtLeast\|versionOlder\|when 2[0-9]\.[0-9][0-9]\|TODO.*2[0-9]\.[0-9][0-9]" \ + --include=*.nix nixos home-manager lib pkgs flake.nix +``` + +Known example: `nixos/modules/common.nix` carries a `# TODO: Remove if-else when 26.11 releases` +guard. For each hit, evaluate whether the now-current versions make the guard removable and list +candidates. ⏸ Don't delete guards without confirmation — some protect the still-supported stable. + +## Phase 5 — Review remaining flake inputs + +Don't blanket-update. Walk the other inputs deliberately: + +1. List inputs and locked revisions from `flake.lock` (or `nix flake metadata`). +2. For each meaningful input (`libnetRepo`, `devshell`, `determinate-nix`, `ragenix`, `deploy-rs`, + `impermanence`, and the packaged apps like `boardie`, `harmonia`, `copyparty`, `sharry`, …), + compare the locked revision to upstream and summarize notable changes (breaking changes, + relevant fixes). Many inputs `follows` `nixpkgs-unstable` and already moved in Phase 3. +3. Propose a per-input update list with reasons; update the approved ones with targeted + `nix flake update `, not a global update. + +## Phase 6 — Validate + +1. `nix flake check --no-build` (broad eval; reproduces CI's cheap checks). +2. `check-system ` on a representative box, and one exercising the stable channel if the + boxes mix channels. +3. Report eval/build results honestly. On failure, surface the error and stop rather than papering + over it. + +## Wrap-up + +Present a final summary: fork rebase outcome (patches kept/dropped/conflicted), whether a stable +bump is pending or was applied, the lock diff, version-gate cleanup candidates, inputs updated, and +validation results. Leave committing to the maintainer unless asked; if committing, follow the +repo's `area/scope: Capitalized summary` convention.