diff --git a/.agents/skills/upgrade-nixpkgs/SKILL.md b/.agents/skills/upgrade-nixpkgs/SKILL.md new file mode 100644 index 0000000..39831f7 --- /dev/null +++ b/.agents/skills/upgrade-nixpkgs/SKILL.md @@ -0,0 +1,27 @@ +--- +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, update kernel and + release metadata, refresh pins, sweep version-gated TODOs, and review other inputs. Use when the + user wants to update/bump nixpkgs, refresh the pins, or do the periodic nixpkgs/home-manager + upgrade. +--- + +# Upgrade nixpkgs + +Read [`docs/nixpkgs-upgrade.md`](../../../docs/nixpkgs-upgrade.md), the canonical procedure, and +follow its phases in order. + +Key reminders (see the doc for the full steps): + +- It is **guided, not automated** — do the mechanical and investigative work but stop at the ⏸ + points: pushing the fork, resolving rebase conflicts, applying a stable-channel bump, choosing a + new release codename, and deleting version guards. Report the findings 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. +- After refreshing the pins, update `lib/constants.nix` to the current explicit LTS and latest + kernel package attributes, and update the `lib/default.nix` version overlay's `YY.MM` prefix to + the current month. Change its codename only when the stable channel advances. diff --git a/.claude/skills/upgrade-nixpkgs b/.claude/skills/upgrade-nixpkgs new file mode 120000 index 0000000..5722403 --- /dev/null +++ b/.claude/skills/upgrade-nixpkgs @@ -0,0 +1 @@ +../../.agents/skills/upgrade-nixpkgs \ No newline at end of file diff --git a/.claude/skills/upgrade-nixpkgs/SKILL.md b/.claude/skills/upgrade-nixpkgs/SKILL.md deleted file mode 100644 index 1937873..0000000 --- a/.claude/skills/upgrade-nixpkgs/SKILL.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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 2280eca..251b125 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,8 +65,9 @@ Common ones: `$INSTALLER`. For bringing up a new box end to end follow the guided procedure in [`docs/install-box.md`](docs/install-box.md). - `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). + (rebasing the `devplayer0` nixpkgs fork, stable-release bumps, kernel and release-metadata + refreshes, 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 @@ -211,10 +212,13 @@ in churn. command, option or upstream technical term such as QEMU's machine type. - Commit subjects follow `area/scope: Capitalized summary` (e.g. `nixos/home: ...`); keep logically distinct changes in separate commits. Aim for 50-character subjects and do not exceed 72 - characters. Wrap commit bodies at 72 columns. A concise body describing the change and its - rationale is welcome when the subject alone does not provide enough context — keep it to the - essentials rather than restating the diff. `Co-Authored-By` is the only trailer used here; do - **not** add a `Claude-Session` link (or any other session/tooling trailer). + characters. Hard-wrap commit body lines at 72 characters; Git preserves an unwrapped `-m` + argument as one long line, so include literal line breaks or use a commit-message file. Before + reporting a commit, inspect `git show -s --format=%B HEAD` and amend it if any line exceeds 72 + characters. A concise body describing the change and its rationale is welcome when the subject + alone does not provide enough context — keep it to the essentials rather than restating the diff. + `Co-Authored-By` is the only trailer used here; do **not** add a `Claude-Session` link (or any + other session/tooling trailer). - **"Logically distinct" means unrelated** — two different applications, two boxes that have nothing to do with each other, a drive-by fix that happens to sit in a file you were editing anyway. One piece of work stays in one commit even when it touches a config, several docs and a switch: if the diff --git a/docs/nixpkgs-upgrade.md b/docs/nixpkgs-upgrade.md index 25d0fd5..f98d952 100644 --- a/docs/nixpkgs-upgrade.md +++ b/docs/nixpkgs-upgrade.md @@ -2,13 +2,14 @@ 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. +shared agent-skill entry point exists at `.agents/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. +stable-channel configuration, choosing a new release codename, 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. @@ -43,6 +44,7 @@ stable pins) has to agree on one NixOS stable release, so establish it up front. 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. + - Choose a new `lib/default.nix` `versionOverlay` codename (Phase 4 updates it). - 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. @@ -83,7 +85,28 @@ 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 +## Phase 4 — Refresh kernels and release metadata + +Update the repository values that deliberately move with nixpkgs upgrades: + +1. In `lib/constants.nix`, inspect the kernel attributes available from the refreshed nixpkgs pins + and update both explicit selections: + - `kernel.lts` → the newest upstream long-term-support kernel carried by nixpkgs. + - `kernel.latest` → the newest kernel series carried by nixpkgs. + Keep explicit `pkgs.linuxKernel.packages.linux_X_Y` attributes rather than replacing them with + moving aliases. Confirm both attributes exist in the unstable and stable package sets used by + the boxes; if the newest choice is unavailable on stable, report that instead of breaking the + shared constant. +2. In `lib/default.nix`, update the `versionOverlay` values: + - Set the leading `YY.MM` in `trivial.release` to the current year and month. Preserve the + `:u-${prev.trivial.release}` suffix. + - If Phase 1 found a new NixOS stable release, ⏸ ask the maintainer to choose or approve a new + `trivial.codeName`, then update it as part of the coordinated stable bump. Otherwise retain the + existing codename. + +Show these edits alongside the input changes in the upgrade summary. + +## Phase 5 — 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: @@ -97,7 +120,7 @@ Known example: `nixos/modules/common.nix` carries a `# TODO: Remove if-else when 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 +## Phase 6 — Review remaining flake inputs Don't blanket-update. Walk the other inputs deliberately: @@ -109,17 +132,17 @@ Don't blanket-update. Walk the other inputs deliberately: 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 +## Phase 7 — 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. + boxes mix channels. This must exercise the refreshed kernel constants on both 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. +bump is pending or was applied, kernel and release-metadata changes, 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.