YOUR JOURNEY
12 / 18
02THE NIXOS SYSTEM 5 MIN READ
LESSON 12 / A MAINTAINABLE SYSTEM

Keep the config.
Understand the state.

A few habits make a declarative system easier to live with.

Version your source, read upgrade notes, and distinguish package revisions from compatibility settings.

Explore the lesson
~$ NixOS examples · try them in a VM.
THE NIX MODEL01 / 03
Drag to rotate

Commit the configuration you understand.

Record configuration in Git
12.1TWO DIFFERENT VERSIONS

stateVersion is not an update selector.

system.stateVersion preserves compatibility defaults for stateful parts of the system. Keep the value from your original installation unless you have reviewed what changing it requires. It does not select your Nixpkgs revision or upgrade packages.

Your Nixpkgs source controls the package and module definitions used for a rebuild. In a channel workflow, that source comes from channels; in a flake workflow, it comes from locked inputs. We will use flakes next.

terminal · use your actual filenames
# In your configuration directory:
git diff
git add configuration.nix tools.nix
git commit -m "Describe workstation tools"
 
# Preserve the existing system.stateVersion.
Next section: Make each change understandable.
12.2A HABIT WORTH KEEPING

Make each change understandable.

Change one concern at a time, inspect the diff, build, activate, then check the affected behavior. Keep configuration files in version control, excluding secrets. Do not assume Git alone backs up service data.

Your system can now be described, split into modules, and rebuilt. The remaining question is how to keep everyone evaluating those modules against the same package collection. That is where a lock file helps.

TAKE THIS WITH YOU

Update package inputs deliberately; do not routinely bump system.stateVersion.

Go a little deeperWhen to update stateVersion
UP NEXT

Anatomy of a flake

A flake standardizes what a Nix project consumes and exposes.

Next lesson