From f06c38fd1e3e6b4d6807006328d9654daf0b2b45 Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Fri, 28 Feb 2020 14:27:39 +0100
Subject: [PATCH] Improve the upgrade page

---
 content/en/admin/upgrading.md | 45 +++++++++++++++++++++++++----------
 1 file changed, 32 insertions(+), 13 deletions(-)

diff --git a/content/en/admin/upgrading.md b/content/en/admin/upgrading.md
index 501f0901..3962bb55 100644
--- a/content/en/admin/upgrading.md
+++ b/content/en/admin/upgrading.md
@@ -10,7 +10,9 @@ menu:
 When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended.
 {{< /hint >}}
 
-Mastodon releases correspond to git tags. First, switch to the `mastodon` user:
+Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
+
+To begin, switch to the `mastodon` user:
 
 ```bash
 su - mastodon
@@ -18,38 +20,55 @@ su - mastodon
 
 And navigate to the Mastodon root directory:
 
-Download the releases’s code, assuming that the version is called `v2.5.0`:
+```bash
+cd /home/mastodon/live
+```
+
+Download the releases’s code, assuming that the version is called `v3.1.2`:
 
 ```bash
 git fetch --tags
-git checkout v2.5.0
+git checkout v3.1.2
 ```
 
-**The release page contains a changelog, and below it, upgrade instructions**. This is where you would execute them, for example, if the release mentions that you need to re-compile assets, you would execute:
+Now execute the upgrade instructions that are included in that version's release notes on GitHub. Because different releases require different instructions, we do not include any instructions on this page.
 
-```bash
-RAILS_ENV=production bundle exec rails assets:precompile
-```
+{{< hint style="info" >}}
+You can safely skip intermediate releases when upgrading from an old version. You do not need to individually check them out. However, you do need to keep track of the instructions with each release. Most instructions overlap, you just need to make sure you execute everything at least once.
+{{< /hint >}}
 
-After you have executed all special release-specific instructions, the last thing remaining is restarting Mastodon. _Usually_ the streaming API is not updated, and therefore does not require a restart. Restarting the streaming API can lead to an unusually high load on the server, so it is advised to avoid it if possible.
-
-Switch back to root:
+After you have executed the instructions from the release notes, switch back to root:
 
 ```bash
 exit
 ```
 
-You would restart Sidekiq:
+Restart **background workers**:
 
 ```bash
 systemctl restart mastodon-sidekiq
 ```
 
-And you would reload the web process to avoid downtime:
+And reload the **web process**:
 
 ```bash
 systemctl reload mastodon-web
 ```
 
-**That’s all!** You’re running the new version of Mastodon now.
+{{< hint style="info" >}}
+The `reload` operation is a zero-downtime restart, also called "phased restart". As such, Mastodon upgrades usually do not require any advance notice to users about planned downtime. In rare cases, you can use the `restart` operation instead, but there will be a (short) felt interruption of service for your users.
+{{< /hint >}}
 
+Rarely, the **streaming API** server is also updated and requires a restart:
+
+```bash
+systemctl restart mastodon-streaming
+```
+
+{{< hint style="danger" >}}
+The streaming API server is updated very rarely, and in most releases, does *not* require a restart. Restarting the streaming API leads to an increased load on your server as disconnected clients attempt to reconnect or poll the REST API instead, so avoid it whenever you can.
+{{< /hint >}}
+
+{{< hint style="success" >}}
+**That’s all!** You’re running the new version of Mastodon now.
+{{< /hint >}}