From a4d33e816ef6c5baaed4eb65e826cd5aa75c0343 Mon Sep 17 00:00:00 2001
From: wiki-me <68199012+wiki-me@users.noreply.github.com>
Date: Sat, 6 Jan 2024 20:01:10 +0200
Subject: [PATCH] Improve documentation around upgrading nix (#9679)

* Improve documentation around upgrading nix, add replacing nix channel with new one

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/installation/upgrading.md | 35 ++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/manual/src/installation/upgrading.md b/doc/manual/src/installation/upgrading.md
index 6d09f54d8..d1b64b80b 100644
--- a/doc/manual/src/installation/upgrading.md
+++ b/doc/manual/src/installation/upgrading.md
@@ -1,5 +1,40 @@
 # Upgrading Nix
 
+> **Note**
+>
+> These upgrade instructions apply for regular Linux distributions where Nix was installed following the [installation instructions in this manual](./index.md).
+
+First, find the name of the current [channel](@docroot@/command-ref/nix-channel.md) through which Nix is distributed:
+
+```console
+$ nix-channel --list
+```
+
+By default this should return an entry for Nixpkgs:
+
+```console
+nixpkgs https://nixos.org/channels/nixpkgs-23.05
+```
+
+Check which Nix version will be installed:
+
+```console
+$ nix-shell -p nix -I nixpkgs=channel:nixpkgs-23.11 --run "nix --version"
+nix (Nix) 2.18.1
+```
+
+> **Warning**
+>
+> Writing to the [local store](@docroot@/store/types/local-store.md) with a newer version of Nix, for example by building derivations with `nix-build` or `nix-store --realise`, may change the database schema!
+> Reverting to an older version of Nix may therefore require purging the store database before it can be used.
+
+Update the channel entry:
+
+```console
+$ nix-channel --remove nixpkgs
+$ nix-channel --add https://nixos.org/channels/nixpkgs-23.11 nixpkgs
+```
+
 Multi-user Nix users on macOS can upgrade Nix by running: `sudo -i sh -c
 'nix-channel --update &&
 nix-env --install --attr nixpkgs.nix &&