Day 79 — 26.05 release notes

Updated

July 30, 2026

Day 79 — 26.05 release notes

Stage VII · ~4h
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 volume: 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 day exists

Upgrades fail when people skip release notes and only chase build errors one by one. Day 80 plans 26.05→26.11; today you learn 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 24.11/25.05 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 volume: record your current stateVersion; do not bump it casually on Day 79. If notes require a migration path, put it on the Day 80 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

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 | Day 80 |
| 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/90daysofx/02-nixos/day79/notes-raw
cd ~/lab/90daysofx/02-nixos/day79

Lab 1 — Capture current pin

cd /path/to/your/flake
nix flake metadata | tee ~/lab/90daysofx/02-nixos/day79/metadata.txt
nix --version | tee ~/lab/90daysofx/02-nixos/day79/nix-version.txt
rg -n "stateVersion" -g '*.nix' | tee ~/lab/90daysofx/02-nixos/day79/stateVersion-hits.txt

Optional lock peek:

jq -r '.nodes.nixpkgs.original,.nodes.nixpkgs.locked' flake.lock \
  | tee ~/lab/90daysofx/02-nixos/day79/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/90daysofx/02-nixos/day79/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 Day 80/83 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/90daysofx/02-nixos/day79/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/90daysofx/02-nixos/day79/check.log

Lab 5 — Personal “gotchas from 26.05”

Write 5 bullets in IMPACT.md under “What I almost missed.” These feed Day 81 troubleshooting and Day 90 teach-back.

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 Day 80 runbook step.

Lab 6 — Feed Day 80

Create UPGRADE-SEEDS.md with:

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

Do not perform the upgrade today 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 “Yarara 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
Day 80 seeds noted
Three personal gotchas

Commit

git add .
git commit -m "day79: annotate 26.05 release notes against flake"

Write three personal gotchas before continuing.

Tomorrow

Day 80 — Upgrade planning 26.05→26.11: written dry-run runbook, risks, tests-first, rollback—no requirement to upgrade prod yet.

Day 79 — 26.05 release notes

Why this day 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

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 Day 80

Common gotchas

Checkpoint

Commit

Tomorrow

Theory 3 — `stateVersion` is not a fashion number