Nixpkgs: Release Notes for 18.03 do not tell how to upgrade

[dasuxullebt]

Issue description

The release notes for NixOS 18.03 are elaborate, but should contain a few lines where they tell which commands to use to actually upgrade.

Steps to reproduce

Open browser, go to website.

[grahamc]

Additionally, the template for future release notes, and the "how to release" documentation should suggest this for all future releases.

[Anton-Latukha]

Also:

/etc/nixos/configuration.nix:

  # This value determines the NixOS release with which your system is to be
  # compatible, in order to avoid breaking some software such as database
  # servers. You should change this only after NixOS release notes say you
  # should.
  system.stateVersion = "17.09"; # Did you read the comment?

I didn't saw when command was issued to change this.

I read the release notes, news and available information.
Waited for the command to do it, but not found one.

Anyway, couple days after release I changed "17.09" -> "18.03".

[emmanuelrosa]

Setting system.stateVersion correctly is tricky because it requires keeping track of the history of changes which are controlled by system.stateVersion.

For instance, in 17.09 the default version of postgres was changed so stateVersion = "17.03" is used to keep the old postgres and hence allow postgres to read the existing database files. So, lets say you're using postgres and decide to keep it the same, so you leave system.stateVersion alone.

Then comes the next release which states that stateVersion affects matrix-synapse. If you don't use matrix-synapse you may be inclined to think that setting stateVersion to 18.03 is safe, when in fact it's not because because the system.stateVersion rules from the previous release could still be in play.

One way to handle this (for now) is to maintain a system.stateVersion matrix; A (HTML) table which shows the possible system.stateVersion values and what they do. That way such important information is not buried in years-worth of release notes.

The real way to fix this is to have Nix support for package deprecation. That way package devs have a way to programmatically say please don't use this package anymore, use this instead, and please do so before upgrading to the next release. But thus far I've found it quite challenging to crack this nut.

[vcunat]

We could add a link to another section of the manual. This didn't occur to me, as focused on the changes since the previous release. EDIT: well, I had put such links into the release announcements instead.

I don't understand the (perceived) issue about stateVersion. As I see it, the main point are a few more complex cases where upgrading could not be reversed naturally; that would go against some basic nix* advantages, so there's the option to let the format of the "state" lag behind. Only a handful services use this.

[jacobjwebber]

Hello I am a beginner user of NixOS.
First of all thank you for all the work you are doing on this. I did find it annoying not to find the instructions on how to upgrade not included in the release notes - I found the instructions via googling, coming here and seeing the link in @vcunat 's comment. Also (not sure if this is the correct place to raise it) the upgrade instructions did not work for me. The

# nixos-rebuild switch --upgrade

command required sudo privileges. However, if you add the 18.03 channel as a normal user then it wont upgrade the channel for the super user.

There is the following note

Note: Channels are set per user. This means that running nix-channel --add as a non root user (or without sudo) will not affect configuration in /etc/nixos/configuration.nix

but it still doesn't make the commands correct (or, in my opinion, make what is going on particularly clear). Perhaps the manual should tell you to switch to super user before running the channel commands?

It would have made my upgrade faster in smoother to have precise upgrade commands in the release notes (with priveleges required).

Apologies if I am doing it all wrong - I appreciate this is not a support forum. But there does seem to be a bug in the documentation and I thought a beginners perspective might be useful.

[stale[bot]]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.