Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: nixos: update system.stateVersion disclaimer #74138

wants to merge 1 commit into
base: master


Copy link

ilikeavocadoes commented Nov 25, 2019

Motivation for this change

A year ago I asked on discourse if I should ever want to change my system.stateVersion ( I got my answer, but I thought the comment on the default configuration.nix is a bit misleading. It's meant to tell the user that the user doesn't need to change this value ever, but instead left me to wonder if it should regularly be changed.

Many new users seem to have this exact confusion. By a quick search I found at least 4 threads on discourse where someone asks the same question. I also periodically get hearts on discourse to my last message in the thread, where I state that I understand now that I should never change system.stateVersion. The thread also has more than 1 200 views, which is way more than a simple question should get. I think this is an indication that many users search for an answer to this same question.

I propose that the message to be reworded, but am unsure about the best wording. My current change is just an example, which I intend to replace with a better text. Any ideas about a better message?

Copy link

nixos-discourse commented Nov 25, 2019

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

Copy link

ryantm commented Nov 26, 2019

Here's another official place that documents stateVersion:

Copy link

earksiinni commented May 27, 2020

I created #88948 not knowing that this PR already existed.

I think that this PR moves in the right direction, but I would make two suggestions:

  1. The updated comment doesn't explain why stateVersion should never need to change. OTOH, that setting's description does it quite well:
    description = ''
    Every once in a while, a new NixOS release may change
    configuration defaults in a way incompatible with stateful
    data. For instance, if the default version of PostgreSQL
    changes, the new version will probably be unable to read your
    existing databases. To prevent such breakage, you should set the
    value of this option to the NixOS release with which you want
    to be compatible. The effect is that NixOS will use
    defaults corresponding to the specified release (such as using
    an older version of PostgreSQL).
    It‘s perfectly fine and recommended to leave this value at the
    release version of the first install of this system.
    Changing this option will not upgrade your system. In fact it
    is meant to stay constant exactly when you upgrade your system.
    You should only bump this option, if you are sure that you can
    or have migrated all state on your system which is affected
    by this option.
    Why don't we simply use this description as the comment? IMHO, the description should first be updated to make it a little more beginner-friendly as it assumes a high level of knowledge about NixOS' internal structure (e.g., "You should only bump this option, if you are sure that you can or have migrated all state on your system which is affected by this option").
  2. We should get rid of the "Did you read the comment?" parenthetical. At best, it has a bad doc smell--if you have to tell the reader to reread the previous section, there's a more fundamental problem. At worst, it has a somewhat passive-aggressive tone and could even be interpreted as condescending toward the reader.
Copy link

maralorn commented Jun 15, 2020

I it is worth noting that the comment in the configuration.nix has been changed in january 2020:


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.