treewide: rewrite stateVersion docs (again), clean up some stateVersion usages (again)

[K900]

Description of changes

This is as actionable (or really NON-actionable) as I can make it sound, I think.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 23.11 Release Notes (or backporting 23.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

[fricklerhandwerk]

Docs LGTM, also replacing the absolute paths with modulesPath. Not sure about the other details, so please wait for actual maintainers.

[K900]

r? @colemickens for Azure stuff, @mkg20001 for LXD stuff

[colemickens]

To be honest, I haven't touched that stuff in years, and have less than no incentive to now. My last attempt was out-of-tree, which is probably what I'd recommend going forward. In fact, I'd recommend deprecating and planning to remove the Azure stuff from the tree, but I have no idea if folks are using any of it. Sorry I don't have a better answer.

[teto]

Even if an application can upgrade automatically its data, often it can not downgrade the data, making rollbacks obsolete. I understood stateVersion also as a warning to make sure I create backups otherwise I would not be able to rollback.

[tejing1]

The seems too tangential to include here, as it's not really about stateVersion, just another aspect of how nixos interacts with state. This description is already long enough that a fair chunk of people won't read it all.

[K900]

It's also not about backups really - automated upgrades happen in nixpkgs all the time without stateVersion bumps.

[mkg20001]

👍 for lxd

[maralorn]

I commented on the comment. Changes there then potentially need to be mirrored to the option docs.

[maralorn]

I think this is good and clear. A few thoughts:

• "This option defines the first version of NixOS you have installed on this particular machine" kinda blurs the difference between the current install and previous installs of nixos on the same machine. It’s hopefully not a confusion anyone runs into, but it seems like an unneccessary confusion. Maybe "This option is neccessary to remember the version of NixOS used during initial install on this particular machine."?

• "with data not managed by NixOS configuration" this is confusing. The data is not generated from NixOS configuration, but file location, services, etc. are managed by NixOS configuration. We are looking for a beginner friendly term for "stateful data", right? How about simply "compatibility with application data (e.g. databases) that was created by older NixOS versions."

• For my personal taste, this comment is too long. I would confine more of the warnings into the option documentation. That’s exactly why the comment previously said "a) just leave this, it’s fine and b) before changing read the docs". In the end I have no clue what works better for users. Just saying, that we maybe need a different solution before half of configuration.nix is an essay about stateVersion.^^

• Why drop the the nixos.org link? I assume for many users it is the more natural interface to read options than the man-page which is arguably only semi-made for this.

I would love to see my first two points considered somehow, the second two are nice to have.

[K900]

1. I get the problem, but I think "initial install" can be misread mostly the same way. I can't really think of a good way to phrase this to make it clear we mean "the first version of this install" without using "install" is a noun, which is confusing.

2. Yes, that was the idea. I think I like your version, though "application data" is technically never created by NixOS, it's created by applications - but that's nitpicky and not relevant to the target audience for this comment.

3. Originally it was intro, 3 points, see also. Now it's 4 points (with number 3 being added on suggestion from @tejing), and I think this is also my upper limit for how many points it should have. I'd like to condense it more, but I think more points that are punchier individually is better than less points that don't hit as hard.

4. No particular reason, I think it just got lost in the sauce. I'll put it back.

[maralorn]

If this were a book I would be very opposed to the one paragraph - one sentence policy. I think I would probably just pack the points 2 to 5 in one paragraph. That way we have three paragraphs "What is this, what to do, further reading". But that’s really just my intuition. You can leave it as is.

[K900]

I actually intentionally separated these into individual lines, because I want them to scan as individual points. For a book, you'd probably want to write the whole thing very differently. This is basically our equivalent to the "this is not a place of honor" messages.

[K900]

Applied [2] and [4]. Still thinking of a good way to phrase [1].

[evils]

how about something like this for the config comment?

# This option lets NixOS know which release established the stateful data [on the system]
# (such as versioned databases, files, and their paths), and lets future releases stay compatible [with it].
# It is strongly recommended to leave this unchanged, changing this may result in data loss.
# Read the documentation [link to description?] if you're considering changing this.

[K900]

Not scary enough, IMO.

[tejing1]

This option lets NixOS know which release established the stateful data on the system

This sentence is good. It's the most intuitive single-line answer to "what does this option do" I've seen yet.

I still think we should keep the punchy later lines, but the first paragragh could be changed to:

# This option lets NixOS know which release established the stateful data on the system
# so that release upgrades do not break compatibility with existing state.

[tejing1]

Did you mean to remove the nixos manual url in that last force-push?

[K900]

No, fixed.

[tejing1]

Yeah, I like where the wording is at now.