fix: upgrade guide 0.5->0.8

UPGRADE.md

@@ -5,14 +5,27 @@ possible. Please note that not all breaking changes might be included here.
 Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes
 before finalizing the upgrade process.
 
-## unreleased
+## v0.8.0-alpha.1
 
-These changes have not yet been released and this area's purpose is to keep
-track of future changes.
+This version includes a lot of new features, but includes few breaking changes, mostly around the SDKs.
+For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#080-alpha1-2021-10-27).
 
-## v0.4.4-alpha.1
+## v0.7.0-alpha.1
 
-Please head over to the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#040-alpha1-2020-07-08)
+A new SDK has been introduced in this version, please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#070-alpha1-2021-07-13) to get a full overview of the SDK and other breaking changes.
+
+## v0.6.0-alpha.1
+
+BCrypt is now the default hashing algorithm. You must apply SQL migrations for this upgrade, this will invalidate all ongoing self-service flows and purge existing self-service forms. If you wish to keep these records, make a back up of your database prior!
+For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#060-alpha1-2021-05-05).
+
+## v0.5.0-alpha.1
+
+For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#050-alpha1-2020-10-15).
+
+## v0.4.0-alpha.1
+
+Please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#040-alpha1-2020-07-08).
 
 ## v0.3.0-alpha.1
 

docs/docs/guides/upgrade.md

@@ -0,0 +1,77 @@
+---
+id: upgrade
+title: Applying Upgrades
+---
+
+This guide covers basics to consider when upgrading Ory Kratos, please also
+visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) for
+more technical details.
+
+Generally upgrading Ory Kratos can be split into three main steps:
+
+- Make a backup.
+- [Install](/install.md) the new version (depending on how you run Ory Kratos).
+- Run [`kratos migrate sql`](../cli/kratos-migrate-sql.md) to run the
+  appropriate SQL queries.
+
+Ory Kratos will run the `migrate sql` command for all versions. For example when
+upgrading from v0.6 to v0.8, the migrations will be run for v0.6 to v0.7 and
+then for v0.7 to v0.8. As such upgrading from any version to the latest version
+directly is possible. Should you run into problems with a direct upgrade,
+consider a stepped upgrade and please visit the community
+[chat](https://slack.ory.sh/) or
+[discussions](https://github.com/ory/kratos/discussions).
+
+:::warning
+
+Back up your data! Applying upgrades can lead to data loss if handled
+incorrectly.
+
+:::
+
+### Upgrading Tips
+
+We recommend taking the following steps to ensure that no data is lost:
+
+> Please note: These are recommendations and should be used in accordance with
+> other Ops best practices. The steps required for a smooth and secure upgrade
+> process may vary with different setups, tech stacks, and environments.
+
+1. Write down a high-level upgrade plan
+
+- Who will perform the upgrade?
+- How will the upgrade be performed?
+- What components are affected?
+
+2. Devise roll-out plan
+
+- When will the upgrade be performed?
+- Will there be an outage?
+- How long will it be?
+- What is your rollback plan?
+
+3. Back up everything!
+4. Run a trial upgrade on a local environment.
+5. Run an upgrade on a staging environment.
+6. Perform tests on staging & prepare production environment.
+7. Run the upgrade on production.
+
+### Breaking changes overview
+
+- **[Ory Kratos v0.8 Breaking changes](https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes)**
+
+- **[Ory Kratos v0.7 Breaking changes](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes)**
+
+- **[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)**
+
+- **[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)**
+
+For older Ory Kratos versions, visit
+[UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md)
+
+:::note
+
+Skip the hassle of applying upgrades to Ory Kratos? Take a look at
+[Ory Cloud](https://www.ory.sh/docs/#ory-cloud).
+
+:::

docs/sidebar.json

@@ -74,7 +74,8 @@
       "guides/https-tls",
       "guides/setting-up-password-hashing-parameters",
       "guides/integration-with-other-systems-using-web-hooks",
-      "guides/tracing"
+      "guides/tracing",
+      "guides/upgrade"
     ]
   },
   "reference/api",