self-hosted: update upgrade path (#1345)

develop-docs/self-hosted/releases.mdx

@@ -4,8 +4,6 @@ sidebar_title: Releases & Upgrading
 sidebar_order: 10
 ---
 
-![CalVer: YY.MM.MICRO](https://img.shields.io/badge/calver-YY.MM.MICRO-ad6caa.svg)
-
 Sentry cuts regular releases for self-hosting to keep it as close to [sentry.io](https://sentry.io) as possible. We decided to follow a monthly release schedule using the [CalVer](https://calver.org/#scheme) versioning scheme, with a primary release on the [15th of each month](https://github.com/getsentry/self-hosted/blob/704e4c3b5b7360080f79bcfbe26583e5a95ae675/.github/workflows/release.yml#L20-L24). We don't patch old versions, but if a bug is bad enough we may cut an out-of-cycle point release, which, like our regular monthly releases, is a snapshot of the latest versions of all of our components. You can find the [latest release](https://github.com/getsentry/self-hosted/releases/latest) over at the [releases section of our self-hosted repository](https://github.com/getsentry/self-hosted/releases/).
 
 <Alert title="Why CalVer?" level="info">
@@ -22,50 +20,36 @@ Sentry cuts regular releases for self-hosting to keep it as close to [sentry.io]
 
 We encourage everyone to regularly update their Sentry installations to get the best and the most recent Sentry experience.
 
-To upgrade, all you need to do is download or check out the version of self-hosted repository you want, replace your existing folder's contents with that, and then run `./install.sh`.
+Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information.
 
-<Alert title="Configuration Updates" level="info">
-We may have some updated configuration, especially for new features, so always check the example config files under the <Link to="https://github.com/getsentry/self-hosted/blob/master/sentry/">sentry directory</Link> and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades.
-</Alert>
+We assume you've cloned the self-hosted repository, so checkout the version you want to upgrade to (23.11.0 as an example).
 
-Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information.
+```bash
+git fetch
+git checkout 23.11.0
+```
 
 <Alert title="Warning" level="warning">
-  There are certain hard-stops you need to go through when upgrading from earlier versions. Please read the <Link to="#hard-stops">hard-stops</Link> section below for a list.
+  If you upgrade infrequently, it's less likely that upgrading to the latest version will work.
+  Please refer to <Link to="#hard-stops">Hard Stops</Link> for how to incrementally upgrade to more recent versions.
 </Alert>
 
-If you downloaded self-hosted repository using Git clone, the upgrade commands should look like this:
+We may have some updated configuration, especially for new features, so always check the example config files under the <Link to="https://github.com/getsentry/self-hosted/blob/master/sentry/">sentry directory</Link> and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades.
+
+Finally, to upgrade, just run `./install.sh`.
 
-```bash
-# Assuming your destination upgrade version is 24.3.0
-VERSION="24.3.0"
-git fetch
-git checkout ${VERSION}
-sudo ./install.sh
-```
 
 ### Hard Stops
 
-We have three hards stops that you need to go through in order to pick up significant database changes:
-
-1. If you are coming from a version prior to `9.1.2`, you first need to upgrade to `9.1.2` and follow the next steps:
-   ```
-   <your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> 23.6.2 -> latest
-   ```
-1. If you are coming from `9.1.2`, you first need to upgrade to `21.5.0` and follow the next steps:
-   ```
-   <your.sentry.version> -> 21.5.0 -> 21.6.3 -> 23.6.2 -> latest
-   ```
-1. If you are coming from a version prior to `21.6.3`, you first need to upgrade to `21.6.3`:
-   ```
-   <your.sentry.version> -> 21.6.3 -> 23.6.2 -> latest
-   ```
-1. If you are coming from a version prior to `23.6.2`, you first need to upgrade to `23.6.2`:
-  ```
-   <your.sentry.version> -> 23.6.2 -> latest
-   ```
-
-Any other case (`23.6.2+`), you should be able to upgrade to the latest version directly. We'd recommend you skip `23.7.0` to avoid issues around database migrations and the django 3 upgrade.
+These are the hard stops that you need to go through in order to pick up significant database changes:
+
+```
+<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> 23.6.2 -> 23.11.0 -> latest
+```
+
+Versions to avoid upgrading to:
+- `23.7.0` (issues around database migrations and the Django 3 upgrade)
+
 
 ## Nightly Builds