From 3cfa0630d6b1c392ed72f8b098beb892ab1e103c Mon Sep 17 00:00:00 2001
From: Evilham <contact@evilham.com>
Date: Fri, 23 Dec 2022 10:54:37 +0100
Subject: [PATCH] [docs] Add UPDATING documenting important and breaking
 changes

The first example of these changes relates to the latest Nextcloud
upgrades to major version 24.

Operators are now expected to read the latest version this file before
updating their instances.
---
 UPDATING.md      | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/updating.md |  1 +
 mkdocs.yml       |  1 +
 3 files changed, 49 insertions(+)
 create mode 100644 UPDATING.md
 create mode 120000 docs/updating.md

diff --git a/UPDATING.md b/UPDATING.md
new file mode 100644
index 0000000..80277ca
--- /dev/null
+++ b/UPDATING.md
@@ -0,0 +1,47 @@
+# Updating
+
+It is quite important for operators to check this file before updating their
+production instances, as it may contain information that is critical for good
+continuity of the services.
+
+
+# Kinds of breaking changes
+
+## Nextcloud upgrades
+
+Nextcloud upgrades must be carried out in a very specific order, if you follow
+DD closely you should not have issues with this on 2023 and beyond.
+
+However, if you run an older instance, please find the
+**2022-12 - Nextcloud 24** section on this document, and follow the commands
+closely.
+
+Further major upgrades will be documented here too, but they should have
+little to no impact.
+
+
+# Important changes in reverse chronological order
+
+## 2022
+
+### 2022-12 - Nextcloud 24
+
+Starting with commits in december, DD's blessed Nextcloud version is 24.0.8.
+
+Work is already being carried out to upgrade this to major version 25.
+
+In order to safely upgrade to major version 24, the upgrade must be performed
+step-wise:
+
+    # Latest commit with NC major version 21 by default
+    ./dd-ctl update db4a6d14e9a05ee1b0334aaf87af31703a4ae4d0
+    # Upgrade to NC version 22
+    ./dd-ctl update cbb4e06e896da40430d66435589ab5ea8cf71420
+    # Upgrade to NC version 23
+    ./dd-ctl update 57c87d7172579b8fbe0d8249f47ee0966621e252
+    # Upgrade to NC version 24.0.8  (latest minor on december 2022)
+    ./dd-ctl update f55e830e2cd3071aceb604642fcfb5fdd8d5df17
+    #
+    # Upgrade to latest state of DD
+    # (read more recent notices of important changes before running this)
+    #./dd-ctl update
diff --git a/docs/updating.md b/docs/updating.md
new file mode 120000
index 0000000..535d93e
--- /dev/null
+++ b/docs/updating.md
@@ -0,0 +1 @@
+../UPDATING.md
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index c9e5cd0..0daee51 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -58,6 +58,7 @@ nav:
 - index.ca.md
 - index.es.md
 - install.ca.md
+- updating.md
 - customising.ca.md
 - integrations.ca.md
 - post-install.ca.md