FAQ/When do I update stateVersion: Difference between revisions

(One intermediate revision by the same user not shown)

Line 29:

== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==

~~Generally~~, ~~it is used to inform NixOS what versions of packages you might have previously installed. This~~ is ~~used to ensure correct data migration for certain packages~~<ref name=":0" />~~. Since NixOS configurations are stateless~~, ~~and therefore cannot know what data may already be~~ on ~~your system, there is no other way~~ to ~~identify this~~.

Currently, this is undefined<ref name=":1" />, though the intent is to keep track of on-disk state versions that are not supposed to change with the configuration.

~~{{nixos:option|~~system.stateVersion~~}} in practice is also used for other potential issues that stem from version upgrades~~<~~ref name=":1"~~ /> ~~- it is somewhat controversial what and what not it should be used~~ for, ~~resulting in many different use cases~~. ~~The current and historic lack of a clear definition of what~~ it ~~does~~ is ~~part of why it cannot be updated~~.

As a result, modules can effectively use <code>system.stateVersion</code> for anything, which makes the effects of changing it unpredictable.

Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.

== References ==

</noinclude>

@@ Line 29: / Line 29: @@
 == What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==
-Generally, it is used to inform NixOS what versions of packages you might have previously installed. This is used to ensure correct data migration for certain packages<ref name=":0" />. Since NixOS configurations are stateless, and therefore cannot know what data may already be on your system, there is no other way to identify this.
+Currently, this is undefined<ref name=":1" />, though the intent is to keep track of on-disk state versions that are not supposed to change with the configuration.
-{{nixos:option|system.stateVersion}} in practice is also used for other potential issues that stem from version upgrades<ref name=":1" /> - it is somewhat controversial what and what not it should be used for, resulting in many different use cases. The current and historic lack of a clear definition of what it does is part of why it cannot be updated.
+As a result, modules can effectively use <code>system.stateVersion</code> for anything, which makes the effects of changing it unpredictable.
+Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.
 == References ==
 </noinclude>