Reading release notes (26.05)

Updated

July 30, 2026

Reading release notes (26.05)

Goal: Read the official NixOS 26.05 “Yarara” release notes (and related nixpkgs/Nix notes as needed), then produce an annotated impact checklist for your flake—not a blog summary.

Important

Baseline for this book: NixOS / nixpkgs 26.05. Primary source beats social media threads. If a note conflicts with a blog, trust the release notes + your eval.

Why this chapter exists

Upgrades fail when people skip release notes and only chase build errors one by one. The upgrade planning chapter plans 26.05→next; this chapter teaches the method on the release you should already be targeting, and capture breakages that still lurk in your modules.

Reading notes is an operator skill equal to writing modules.

Theory 1 — What “a NixOS release” actually is

Artifact	Role
nixpkgs branch `nixos-26.05`	Package + module tree for the release
Release notes	Human-facing breaking changes, renames, deprecations
State version `system.stateVersion`	Migration behavior for stateful options
ISO / channel artifacts	Install media (flakes pin git/github instead)
Nix version shipped/tested	Sometimes separate from nixpkgs cadence
flake.lock	Your actual pinned revisions—not the marketing branch name alone

Flakes pin revisions. Your flake.lock may already be on 26.05 while your brain still follows older blog habits.

nix flake metadata
# note nixpkgs locked rev / ref / lastModified

nix eval --raw .#nixosConfigurations.lab.pkgs.lib.version 2>/dev/null || true
# or inspect lock:
# jq '.nodes.nixpkgs' flake.lock

Theory 2 — How to read release notes like an operator

Do not read linearly once and forget. Use passes:

Pass A — Inventory (30–45 min)

Skim sections:

Breaking changes
Notable renames / option moves
Service-specific notes for software you run
Deprecated options
Kernel / boot / systemd highlights
Security-relevant defaults
NixOS module system / installer notes

Pass B — Personal filter (45–60 min)

For each note, tag:

Tag	Meaning
`N/A`	You don’t use it
`WATCH`	Indirect risk
`ACTION`	Must change config
`DONE`	Already handled
`VERIFY`	Needs rebuild/test to confirm

Pass C — Prove with eval/build

nixos-rebuild build --flake .#<host>
# or
nix build .#nixosConfigurations.<host>.config.system.build.toplevel -L

Search your repo for renamed options:

rg -n "oldOption|services\.foo" -g '*.nix'

Pass D — Warnings are future breakages

evaluation warning: …
trace: obsolete option …

Paste warnings into IMPACT.md as VERIFY/ACTION. Next release often hard-errors them.

Theory 3 — `stateVersion` is not a fashion number

system.stateVersion = "26.05"; # example — only change with understanding

stateVersion tells modules how to migrate on-disk state defaults. Blindly bumping it to “match release” can break stateful services (Postgres data dirs, user settings, etc.). Release notes and module comments matter more than aesthetics.

Rule for this book: record your current stateVersion; do not bump it casually while reading notes. If notes require a migration path, put it on the upgrade planning runbook.

Action	When
Leave unchanged	Default
Bump with migration plan	Notes + module docs say so; backups ready
Mismatch with nixpkgs branch	Allowed and common; understand why

Theory 4 — Cross-check Nix itself

Your syllabus pins modern Nix (book baseline mentions 2.34.x class—verify yours). Release notes for Nix (the evaluator/daemon) are separate from NixOS notes.

nix --version
nix config show | rg -i 'experimental|system|substituter' || true

If CI uses a different Nix than your laptop, note the skew in the checklist—flake eval can differ on experimental defaults and sandbox settings.

Surface	Record
Laptop Nix	version
CI Nix	installer action / version
Lab host Nix	from `nix --version` on host

Theory 5 — Module renames and aliases (kinds of change)

Common historical patterns (examples of kinds, not a complete 26.05 dump—you must read the real notes):

Kind	Example pattern	Response
Option rename	`services.foo` → `services.foo-ng`	Update; don’t live on aliases forever
Nested `settings`	freeform attr moved under `settings`	Follow module type
Package rename	overlay breaks	Fix overlay attr
Default flip	`enable` default changed	Explicit `mkForce`/set
Kernel package set	boot fails on old nvidia/out-of-tree	Pin or update module
Removed service	module gone	Replace or package yourself

When notes say an option is renamed, prefer the new path. Aliases expire.

Theory 6 — Inputs beyond nixpkgs

Your flake may pin:

Input	Why check notes/changelogs
home-manager	`release-26.05` pairing
sops-nix	module option moves
deploy-rs / colmena	activation quirks
disko	device option changes
lanzaboote	SB flow changes

Release notes for NixOS are necessary but not sufficient. Skim changelogs for your inputs when IMPACT is large.

nix flake metadata
# for each input: note ref + whether it follows nixpkgs

Theory 7 — Severity and scheduling

Tag	SLA for lab Capstone
ACTION (eval broken)	Fix before next switch
ACTION (runtime risk)	Fix before DR proof
VERIFY	Schedule rebuild this week
WATCH	Note in upgrade seeds
N/A	Drop from working set

Do not turn notes reading into a two-week refactor of modules you do not run.

Worked example — IMPACT.md row

| Note / change | Tag | Repo paths | Action | Owner/date |
|---------------|-----|------------|--------|------------|
| services.foo renamed to services.foo-ng | ACTION | modules/foo.nix:12 | rename option; rebuild | you / today |
| postgres default major | WATCH | hosts/lab/db.nix | verify stateVersion; backup | upgrade runbook |
| plasma something | N/A | — | no desktop | — |
| evaluation warning: obsolete bar | VERIFY | modules/common.nix | rebuild log line 480 | today |

Aim for every ACTION and VERIFY item to reference a file path or explicit N/A reason.

Lab 0 — Workspace

mkdir -p ~/lab/nixos/internals/release-notes/notes-raw
cd ~/lab/nixos/internals/release-notes

Lab 1 — Capture current pin

cd /path/to/your/flake
nix flake metadata | tee ~/lab/nixos/internals/release-notes/metadata.txt
nix --version | tee ~/lab/nixos/internals/release-notes/nix-version.txt
rg -n "stateVersion" -g '*.nix' | tee ~/lab/nixos/internals/release-notes/stateVersion-hits.txt

Optional lock peek:

jq -r '.nodes.nixpkgs.original,.nodes.nixpkgs.locked' flake.lock \
  | tee ~/lab/nixos/internals/release-notes/nixpkgs-lock.txt

Lab 2 — Official notes intake

Open the official NixOS 26.05 release notes (nixos.org manual / nixpkgs nixos/doc/manual release notes for 26.05).
Save the URL in SOURCES.md.
Export or copy key sections into notes-raw/ if you want offline annotation (optional).
Create IMPACT.md with the table from the worked example.

Also add:

URL for any Nix release notes you consulted
HM release notes if you use HM

Lab 3 — Repo audit scripts

cd /path/to/your/flake
rg -n "mkEnableOption|services\.|programs\." -g '*.nix' | head -n 100 \
  | tee ~/lab/nixos/internals/release-notes/options-sample.txt
# search for deprecated names you found in notes:
# rg -n "deprecatedOptionName" -g '*.nix'

For each ACTION, either:

fix now on a branch, or
file as upgrade-planning backlog with severity (blocker / nice)

Avoid giant drive-by refactors while annotating—annotate first; fix blockers only.

Lab 4 — Build verification

nix build .#nixosConfigurations.<host>.config.system.build.toplevel -L \
  2>&1 | tee ~/lab/nixos/internals/release-notes/build.log

If warnings appear, paste them into IMPACT.md as VERIFY/ACTION.

Run relevant checks:

nix build .#checks.<system>.<name> -L \
  2>&1 | tee ~/lab/nixos/internals/release-notes/check.log

Acceptance: Build log captured; every evaluation warning triaged.

Lab 5 — Personal “gotchas from 26.05”

Write 5 bullets in IMPACT.md under “What I almost missed.” These feed troubleshooting and the retrospective.

Also write stateVersion policy in one sentence:

## stateVersion policy
We run stateVersion = "…" on host lab. We will not bump it without: backup, notes citation, and upgrade runbook step.

Lab 6 — Feed upgrade planning

Create UPGRADE-SEEDS.md with:

Item	Why it matters for next upgrade
ACTION leftovers	Must clear or plan
WATCH services	Higher test priority
CI Nix skew	Align before upgrade PR

Do not perform the upgrade in this chapter unless you deliberately expand scope.

Common gotchas

Mistake	Fix
Only reading unofficial summaries	Start from official notes
Bumping `stateVersion` for fun	Read migration semantics first
Assuming lock is 26.05 without checking	`nix flake metadata`
Ignoring warnings that aren’t errors	Warnings become breakages next release
Giant drive-by refactors while annotating	Annotate first; fix blockers only
Forgetting HM/sops inputs	Check paired release branches
Treating blog tips as canonical	Primary notes + your build log

Checkpoint

metadata.txt + nix-version.txt
Official 26.05 URL in SOURCES.md
IMPACT.md tagged N/A/WATCH/ACTION/DONE/VERIFY
Build (and checks) log captured
stateVersion policy recorded
Five “almost missed” bullets
Upgrade seeds noted
Three personal gotchas

Commit

git add .
git commit -m "lab(nixos): annotate 26.05 release notes against flake"

Write three personal gotchas before continuing.

→ Upgrade planning — dry-run runbook to the next release.

Reading release notes (26.05)

Why this chapter exists

Theory 1 — What “a NixOS release” actually is

Theory 2 — How to read release notes like an operator

Pass A — Inventory (30–45 min)

Pass B — Personal filter (45–60 min)

Pass C — Prove with eval/build

Pass D — Warnings are future breakages

Theory 3 — stateVersion is not a fashion number

Theory 4 — Cross-check Nix itself

Theory 5 — Module renames and aliases (kinds of change)

Theory 6 — Inputs beyond nixpkgs

Theory 7 — Severity and scheduling

Worked example — IMPACT.md row

Lab 0 — Workspace

Lab 1 — Capture current pin

Lab 2 — Official notes intake

Lab 3 — Repo audit scripts

Lab 4 — Build verification

Lab 5 — Personal “gotchas from 26.05”

Lab 6 — Feed upgrade planning

Common gotchas

Checkpoint

Commit

Next

Theory 3 — `stateVersion` is not a fashion number