From 877e50033731e894845754c08da97095faff448d Mon Sep 17 00:00:00 2001
From: shreddedbacon <b@benjackson.email>
Date: Wed, 27 Mar 2024 12:15:24 +1100
Subject: [PATCH 1/2] chore: move upgrades and deprecations to docs

---
 DEPRECATIONS.md              | 24 +-----------------------
 UPGRADES.md                  |  8 ++++++++
 docs/deprecations/.pages     |  5 +++++
 docs/deprecations/2.17.0.md  |  8 ++++++++
 docs/deprecations/2.18.0.md  | 11 +++++++++++
 docs/deprecations/summary.md |  9 +++++++++
 docs/requirements.txt        |  1 +
 docs/upgrades/.pages         |  5 +++++
 docs/upgrades/2.10.0.md      |  4 ++++
 docs/upgrades/2.11.0.md      |  5 +++++
 docs/upgrades/policy.md      | 12 ++++++++++++
 mkdocs.yml                   |  3 +++
 12 files changed, 72 insertions(+), 23 deletions(-)
 create mode 100644 UPGRADES.md
 create mode 100644 docs/deprecations/.pages
 create mode 100644 docs/deprecations/2.17.0.md
 create mode 100644 docs/deprecations/2.18.0.md
 create mode 100644 docs/deprecations/summary.md
 create mode 100644 docs/upgrades/.pages
 create mode 100644 docs/upgrades/2.10.0.md
 create mode 100644 docs/upgrades/2.11.0.md
 create mode 100644 docs/upgrades/policy.md

diff --git a/DEPRECATIONS.md b/DEPRECATIONS.md
index 7be2984390..f22f6fc195 100644
--- a/DEPRECATIONS.md
+++ b/DEPRECATIONS.md
@@ -8,26 +8,4 @@ Deprecations will be tracked by the release they are announced in, and then upda
 
 ## Deprecation History
 
-All deprecations are listed below, with the most recent announcements at the top.
-
-### Lagoon v2.18.0
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.18.0
-* The standard drupal based tasks that Lagoon ships with (drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
-* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is becaues the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatability for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
-* The value for `registry` which was previously required by the `lagoon-core` chart is no longer required. If you are using this, you will need to add it under the new `unauthenticatedRegistry` setting when installing `lagoon-remote` in the `lagoon-build-deploy` section of your values file. If you aren't using an actual registry and have the example `disabled-only-use-harbor-via-deploy-controller.invalid` value, then you do not need to do anything except you can now remove the `registry` setting from your core values file.
-* The environment storage return field named `bytesUsed` is deprecated. The actual value stored is `kibibytes`. A new return field called `kibUsed` exists and should be used, the returned data is the same and both fields are still returned. `bytesUsed` will be removed in a future release, make any adjustments now to use `kibUsed`. This will be a breaking change in a future release.
-* `addOrUpdateEnvironmentStorage` is deprecated, `addOrUpdateStorageOnEnvironment` is the replacement to use as it supports the updated input value for `kibUsed`. `addOrUpdateEnvironmentStorage` will be completely removed in a future release.
-* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.
-
-### Lagoon v2.17.0
-
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.17.0
-* This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
-* Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
-* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
-
-### Lagoon v2.16.0
-
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.16.0
-
-There were no planned deprecations announced in this release.
+See https://docs.lagoon.sh/deprecations/summary/
diff --git a/UPGRADES.md b/UPGRADES.md
new file mode 100644
index 0000000000..65b7daddc2
--- /dev/null
+++ b/UPGRADES.md
@@ -0,0 +1,8 @@
+# Lagoon Project Upgrades
+
+Whenever there is important information around versions of Lagoon that may impact the ability to upgrade to a new version, there will be upgrade information notes provided.
+
+You should always read all version release notes, upgrade notes, and deprecation notices for all versions you upgrade to.
+
+## Upgrade Information
+See https://docs.lagoon.sh/upgrades/policy/
\ No newline at end of file
diff --git a/docs/deprecations/.pages b/docs/deprecations/.pages
new file mode 100644
index 0000000000..c26749596d
--- /dev/null
+++ b/docs/deprecations/.pages
@@ -0,0 +1,5 @@
+title: Deprecations
+order: desc
+nav:
+  - Summary: summary.md
+  - ...
\ No newline at end of file
diff --git a/docs/deprecations/2.17.0.md b/docs/deprecations/2.17.0.md
new file mode 100644
index 0000000000..9d0c486938
--- /dev/null
+++ b/docs/deprecations/2.17.0.md
@@ -0,0 +1,8 @@
+
+### Lagoon v2.17.0
+
+Release link: [https://github.com/uselagoon/lagoon/releases/tag/v2.17.0](https://github.com/uselagoon/lagoon/releases/tag/v2.17.0)
+
+* This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
+* Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
+* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
\ No newline at end of file
diff --git a/docs/deprecations/2.18.0.md b/docs/deprecations/2.18.0.md
new file mode 100644
index 0000000000..41859185cb
--- /dev/null
+++ b/docs/deprecations/2.18.0.md
@@ -0,0 +1,11 @@
+
+### Lagoon v2.18.0
+
+release link: [https://github.com/uselagoon/lagoon/releases/tag/v2.18.0](https://github.com/uselagoon/lagoon/releases/tag/v2.18.0)
+
+* The standard drupal based tasks that Lagoon ships with (drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
+* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is becaues the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatability for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
+* The value for `registry` which was previously required by the `lagoon-core` chart is no longer required. If you are using this, you will need to add it under the new `unauthenticatedRegistry` setting when installing `lagoon-remote` in the `lagoon-build-deploy` section of your values file. If you aren't using an actual registry and have the example `disabled-only-use-harbor-via-deploy-controller.invalid` value, then you do not need to do anything except you can now remove the `registry` setting from your core values file.
+* The environment storage return field named `bytesUsed` is deprecated. The actual value stored is `kibibytes`. A new return field called `kibUsed` exists and should be used, the returned data is the same and both fields are still returned. `bytesUsed` will be removed in a future release, make any adjustments now to use `kibUsed`. This will be a breaking change in a future release.
+* `addOrUpdateEnvironmentStorage` is deprecated, `addOrUpdateStorageOnEnvironment` is the replacement to use as it supports the updated input value for `kibUsed`. `addOrUpdateEnvironmentStorage` will be completely removed in a future release.
+* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.
\ No newline at end of file
diff --git a/docs/deprecations/summary.md b/docs/deprecations/summary.md
new file mode 100644
index 0000000000..fdd2643175
--- /dev/null
+++ b/docs/deprecations/summary.md
@@ -0,0 +1,9 @@
+# Deprecations
+
+This is a constantly updated central tracker for deprecations across the suite of Lagoon products.
+
+As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
+
+Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs.
+
+All deprecations should provide a rough timeline (in months or releases). Releases will normally only be listed here if they include planned deprecations.
diff --git a/docs/requirements.txt b/docs/requirements.txt
index de8aa67ed4..1ee97fca86 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -2,3 +2,4 @@ mkdocs-material
 mkdocs-redirects
 mdx_truly_sane_lists
 mkdocs-git-revision-date-localized-plugin
+mkdocs-awesome-pages-plugin
\ No newline at end of file
diff --git a/docs/upgrades/.pages b/docs/upgrades/.pages
new file mode 100644
index 0000000000..622020b57d
--- /dev/null
+++ b/docs/upgrades/.pages
@@ -0,0 +1,5 @@
+title: Upgrades
+order: desc
+nav:
+  - Policy: policy.md
+  - ...
\ No newline at end of file
diff --git a/docs/upgrades/2.10.0.md b/docs/upgrades/2.10.0.md
new file mode 100644
index 0000000000..cb3953c7b3
--- /dev/null
+++ b/docs/upgrades/2.10.0.md
@@ -0,0 +1,4 @@
+### Upgrade to Lagoon v2.10.0
+You must upgrade to Lagoon v2.9.x before upgrading to v2.10.0.
+
+Ensure you read the [release notes](https://github.com/uselagoon/lagoon/releases/tag/v2.10.0) before upgrading to make sure you are aware of all the changes you may be required to do.
\ No newline at end of file
diff --git a/docs/upgrades/2.11.0.md b/docs/upgrades/2.11.0.md
new file mode 100644
index 0000000000..d6af9f6c94
--- /dev/null
+++ b/docs/upgrades/2.11.0.md
@@ -0,0 +1,5 @@
+### Upgrade to Lagoon v2.11.0
+
+You must upgrade to Lagoon v2.10.0 before upgrading to v2.11.0.
+
+Ensure you read the [release notes](https://github.com/uselagoon/lagoon/releases/tag/v2.11.0) before upgrading to make sure you are aware of all the changes you may be required to do.
\ No newline at end of file
diff --git a/docs/upgrades/policy.md b/docs/upgrades/policy.md
new file mode 100644
index 0000000000..812b5b7996
--- /dev/null
+++ b/docs/upgrades/policy.md
@@ -0,0 +1,12 @@
+# Upgrade Policy
+
+Our general policy is that you should upgrade to each minor version before you upgrade to the latest version.
+
+You should check all upgrade requirements and deprecation notices for all versions as you upgrade.
+
+An example of our suggested policy is as follows
+
+* Currently installed v2.14.0, planning to upgrade to v2.17.0
+  1. Upgrade to v2.15.0
+  2. Upgrade to v2.16.0
+  3. Upgrade to v2.17.0
diff --git a/mkdocs.yml b/mkdocs.yml
index 12567b528f..a98b439367 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -161,6 +161,8 @@ nav:
   - Lagoon CLI: https://uselagoon.github.io/lagoon-cli/
   - Lagoon Sync: https://github.com/uselagoon/lagoon-sync
   - Client Libraries: other-tools/client-libraries.md
+- ... | upgrades/*
+- ... | deprecations/*
 
 theme:
   name: 'material'
@@ -238,6 +240,7 @@ markdown_extensions:
 
 plugins:
   - search
+  - awesome-pages
   - redirects:
       redirect_maps:
         # Shortcut URLs for build and compose errors

From f982239ee3f44c25d0cc43f488337fa4bfd45206 Mon Sep 17 00:00:00 2001
From: Toby Bellwood <toby.bellwood@amazee.io>
Date: Wed, 27 Mar 2024 12:15:43 +1100
Subject: [PATCH 2/2] docs: reorder deprecations and upgrades pages

---
 DEPRECATIONS.md                           | 10 +++-----
 UPGRADES.md                               |  5 ++--
 docs/deprecations/.pages                  |  5 ----
 docs/deprecations/summary.md              |  9 --------
 docs/{upgrades => releases}/.pages        |  4 ++--
 docs/releases/2.10.0.md                   | 14 ++++++++++++
 docs/releases/2.11.0.md                   | 18 +++++++++++++++
 docs/releases/2.12.0.md                   | 17 ++++++++++++++
 docs/releases/2.13.0.md                   | 14 ++++++++++++
 docs/releases/2.14.0.md                   |  7 ++++++
 docs/releases/2.14.1.md                   | 14 ++++++++++++
 docs/releases/2.14.2.md                   | 14 ++++++++++++
 docs/releases/2.15.0.md                   | 13 +++++++++++
 docs/releases/2.15.1.md                   | 13 +++++++++++
 docs/releases/2.15.2.md                   | 13 +++++++++++
 docs/releases/2.15.3.md                   | 13 +++++++++++
 docs/releases/2.15.4.md                   | 13 +++++++++++
 docs/releases/2.16.0.md                   | 13 +++++++++++
 docs/{deprecations => releases}/2.17.0.md | 17 +++++++++++---
 docs/{deprecations => releases}/2.18.0.md | 23 +++++++++++++++----
 docs/releases/policy.md                   | 22 ++++++++++++++++++
 docs/releases/x.xx.x.md.tmpl              | 28 +++++++++++++++++++++++
 docs/upgrades/2.10.0.md                   |  4 ----
 docs/upgrades/2.11.0.md                   |  5 ----
 docs/upgrades/policy.md                   | 12 ----------
 mkdocs.yml                                |  3 +--
 26 files changed, 267 insertions(+), 56 deletions(-)
 delete mode 100644 docs/deprecations/.pages
 delete mode 100644 docs/deprecations/summary.md
 rename docs/{upgrades => releases}/.pages (61%)
 create mode 100644 docs/releases/2.10.0.md
 create mode 100644 docs/releases/2.11.0.md
 create mode 100644 docs/releases/2.12.0.md
 create mode 100644 docs/releases/2.13.0.md
 create mode 100644 docs/releases/2.14.0.md
 create mode 100644 docs/releases/2.14.1.md
 create mode 100644 docs/releases/2.14.2.md
 create mode 100644 docs/releases/2.15.0.md
 create mode 100644 docs/releases/2.15.1.md
 create mode 100644 docs/releases/2.15.2.md
 create mode 100644 docs/releases/2.15.3.md
 create mode 100644 docs/releases/2.15.4.md
 create mode 100644 docs/releases/2.16.0.md
 rename docs/{deprecations => releases}/2.17.0.md (58%)
 rename docs/{deprecations => releases}/2.18.0.md (66%)
 create mode 100644 docs/releases/policy.md
 create mode 100644 docs/releases/x.xx.x.md.tmpl
 delete mode 100644 docs/upgrades/2.10.0.md
 delete mode 100644 docs/upgrades/2.11.0.md
 delete mode 100644 docs/upgrades/policy.md

diff --git a/DEPRECATIONS.md b/DEPRECATIONS.md
index f22f6fc195..c71c0d5087 100644
--- a/DEPRECATIONS.md
+++ b/DEPRECATIONS.md
@@ -1,11 +1,7 @@
 # Lagoon Project Deprecation Announcements
 
-## Overview
+Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases).
 
-This file is a constantly updated central tracker for deprecations across the suite of Lagoon products. As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
+## Deprecation and Upgrades policy
 
-Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases). Releases will normally only be listed here if they include planned deprecations.
-
-## Deprecation History
-
-See https://docs.lagoon.sh/deprecations/summary/
+See https://docs.lagoon.sh/releases/policy
diff --git a/UPGRADES.md b/UPGRADES.md
index 65b7daddc2..af15d3b1f3 100644
--- a/UPGRADES.md
+++ b/UPGRADES.md
@@ -4,5 +4,6 @@ Whenever there is important information around versions of Lagoon that may impac
 
 You should always read all version release notes, upgrade notes, and deprecation notices for all versions you upgrade to.
 
-## Upgrade Information
-See https://docs.lagoon.sh/upgrades/policy/
\ No newline at end of file
+## Upgrades and Deprecation policy
+
+See https://docs.lagoon.sh/releases/policy
diff --git a/docs/deprecations/.pages b/docs/deprecations/.pages
deleted file mode 100644
index c26749596d..0000000000
--- a/docs/deprecations/.pages
+++ /dev/null
@@ -1,5 +0,0 @@
-title: Deprecations
-order: desc
-nav:
-  - Summary: summary.md
-  - ...
\ No newline at end of file
diff --git a/docs/deprecations/summary.md b/docs/deprecations/summary.md
deleted file mode 100644
index fdd2643175..0000000000
--- a/docs/deprecations/summary.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Deprecations
-
-This is a constantly updated central tracker for deprecations across the suite of Lagoon products.
-
-As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
-
-Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs.
-
-All deprecations should provide a rough timeline (in months or releases). Releases will normally only be listed here if they include planned deprecations.
diff --git a/docs/upgrades/.pages b/docs/releases/.pages
similarity index 61%
rename from docs/upgrades/.pages
rename to docs/releases/.pages
index 622020b57d..536eef34fa 100644
--- a/docs/upgrades/.pages
+++ b/docs/releases/.pages
@@ -1,5 +1,5 @@
-title: Upgrades
+title: Releases
 order: desc
 nav:
   - Policy: policy.md
-  - ...
\ No newline at end of file
+  - ...
diff --git a/docs/releases/2.10.0.md b/docs/releases/2.10.0.md
new file mode 100644
index 0000000000..5bf0733b80
--- /dev/null
+++ b/docs/releases/2.10.0.md
@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.10.0](https://github.com/uselagoon/lagoon/releases/tag/v2.10.0)
+* lagoon-ui [core-v2.10.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.10.0)
+* lagoon-build-deploy [core-v2.10.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.10.0)
+* lagoon-core chart [1.12.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.12.0)
+
+## Upgrades
+
+### Upgrade to v2.9.x first
+You *must* upgrade to Lagoon v2.9.x before upgrading to v2.10.0. Ensure you read all the linked release notes.
+
+## Deprecations
+
+There are no required actions or considerations with this release
diff --git a/docs/releases/2.11.0.md b/docs/releases/2.11.0.md
new file mode 100644
index 0000000000..5e5e2f25fb
--- /dev/null
+++ b/docs/releases/2.11.0.md
@@ -0,0 +1,18 @@
+#### Release Links
+* lagoon [v2.11.0](https://github.com/uselagoon/lagoon/releases/tag/v2.11.0)
+* lagoon-ui [core-v2.11.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.11.0)
+* lagoon-build-deploy [core-v2.11.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.11.0)
+* lagoon-core chart [1.16.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.16.0)
+
+## Upgrades
+
+### Upgrade to v2.10.x first
+You *must* upgrade to Lagoon v2.10.x before upgrading to v2.11.0. Ensure you read all the linked [release notes](./2.10.0.md#release-links).
+
+### Essential database backups
+Ensure you have a local backup of the api-db and keycloak-db before you commence this update, as there are complex migrations taking place in preparation for the v2.12.0 release.
+
+## Deprecations
+
+### Storage Calculator removed from core
+The storage-calculator service was removed from core in this release, and the service is now included in lagoon-remote.
diff --git a/docs/releases/2.12.0.md b/docs/releases/2.12.0.md
new file mode 100644
index 0000000000..9876bf5efe
--- /dev/null
+++ b/docs/releases/2.12.0.md
@@ -0,0 +1,17 @@
+#### Release Links
+* lagoon [v2.12.0](https://github.com/uselagoon/lagoon/releases/tag/v2.12.0)
+* lagoon-ui [core-v2.12.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.12.0)
+* lagoon-build-deploy [core-v2.12.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.12.0)
+* lagoon-core chart [1.23.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.23.0)
+
+## Upgrades
+
+### Essential database backups
+Ensure you have a local backup of the api-db and keycloak-db before you commence this update. The update of these databases from MariaDB 10.4 to 10.6 should update seamlessly. In the event it does not go smoothly, the image cannot be rolled back owing to incompatible storage engines. You will need to drop the db and restore the backup to get running again.
+
+### Kubernetes 1.21 minimum requirement
+The minimum supported version of Kubernetes is 1.21 as of this release.
+
+## Deprecations
+
+There are no required actions or considerations with this release
diff --git a/docs/releases/2.13.0.md b/docs/releases/2.13.0.md
new file mode 100644
index 0000000000..64a3c0adab
--- /dev/null
+++ b/docs/releases/2.13.0.md
@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.13.0](https://github.com/uselagoon/lagoon/releases/tag/v2.13.0)
+* lagoon-ui [core-v2.13.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.13.0)
+* lagoon-build-deploy [core-v2.13.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.13.0)
+* lagoon-core chart [1.25.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.25.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+### monitoring-urls
+The storage and use of monitoring-urls provided in lagoon.yml has been removed from the API.
diff --git a/docs/releases/2.14.0.md b/docs/releases/2.14.0.md
new file mode 100644
index 0000000000..485dca4efe
--- /dev/null
+++ b/docs/releases/2.14.0.md
@@ -0,0 +1,7 @@
+## Upgrades
+
+This tag was never released, and the [2.14.2](./2.14.2.md) release should be installed instead.
+
+## Deprecations
+
+This tag was never released, and the [2.14.2](./2.14.2.md) release should be installed instead.
diff --git a/docs/releases/2.14.1.md b/docs/releases/2.14.1.md
new file mode 100644
index 0000000000..49c18f08f6
--- /dev/null
+++ b/docs/releases/2.14.1.md
@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.14.2](https://github.com/uselagoon/lagoon/releases/tag/v2.14.2)
+* lagoon-ui [core-v2.14.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.14.2)
+* lagoon-build-deploy [core-v2.14.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.14.2)
+* lagoon-core chart [1.28.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.28.0)
+* lagoon-remote chart [0.76.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.76.0)
+
+## Upgrades
+
+This release was superseded, and the [2.14.2](./2.14.2.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.14.2](./2.14.2.md) release is recommended to be installed instead.
diff --git a/docs/releases/2.14.2.md b/docs/releases/2.14.2.md
new file mode 100644
index 0000000000..86460409fa
--- /dev/null
+++ b/docs/releases/2.14.2.md
@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.14.2](https://github.com/uselagoon/lagoon/releases/tag/v2.14.2)
+* lagoon-ui [core-v2.14.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.14.2)
+* lagoon-build-deploy [core-v2.14.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.14.2)
+* lagoon-core chart [1.28.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.28.0)
+* lagoon-remote chart [0.76.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.76.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release
diff --git a/docs/releases/2.15.0.md b/docs/releases/2.15.0.md
new file mode 100644
index 0000000000..719d8c3241
--- /dev/null
+++ b/docs/releases/2.15.0.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.0](https://github.com/uselagoon/lagoon/releases/tag/v2.15.0)
+* lagoon-ui [core-v2.15.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.0)
+* lagoon-build-deploy [core-v2.15.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.0)
+* lagoon-core chart [1.29.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.29.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
diff --git a/docs/releases/2.15.1.md b/docs/releases/2.15.1.md
new file mode 100644
index 0000000000..b2c3d8d58e
--- /dev/null
+++ b/docs/releases/2.15.1.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.1](https://github.com/uselagoon/lagoon/releases/tag/v2.15.1)
+* lagoon-ui [core-v2.15.1](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.1)
+* lagoon-build-deploy [core-v2.15.1](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.1)
+* lagoon-core chart [1.31.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.31.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
diff --git a/docs/releases/2.15.2.md b/docs/releases/2.15.2.md
new file mode 100644
index 0000000000..1eb50defd4
--- /dev/null
+++ b/docs/releases/2.15.2.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.2](https://github.com/uselagoon/lagoon/releases/tag/v2.15.2)
+* lagoon-ui [core-v2.15.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.2)
+* lagoon-build-deploy [core-v2.15.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.2)
+* lagoon-core chart [1.34.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.34.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
diff --git a/docs/releases/2.15.3.md b/docs/releases/2.15.3.md
new file mode 100644
index 0000000000..1e7ee8395d
--- /dev/null
+++ b/docs/releases/2.15.3.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.3](https://github.com/uselagoon/lagoon/releases/tag/v2.15.3)
+* lagoon-ui [core-v2.15.3](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.3)
+* lagoon-build-deploy [core-v2.15.3](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.3)
+* lagoon-core chart [1.35.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.35.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
diff --git a/docs/releases/2.15.4.md b/docs/releases/2.15.4.md
new file mode 100644
index 0000000000..8bf8b01e63
--- /dev/null
+++ b/docs/releases/2.15.4.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.4](https://github.com/uselagoon/lagoon/releases/tag/v2.15.4)
+* lagoon-ui [core-v2.15.4](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.4)
+* lagoon-build-deploy [core-v2.15.4](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.4)
+* lagoon-core chart [1.36.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.36.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release
diff --git a/docs/releases/2.16.0.md b/docs/releases/2.16.0.md
new file mode 100644
index 0000000000..9426e96644
--- /dev/null
+++ b/docs/releases/2.16.0.md
@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.16.0](https://github.com/uselagoon/lagoon/releases/tag/v2.16.0)
+* lagoon-ui [core-v2.16.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.16.0)
+* lagoon-build-deploy [core-v2.16.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.16.0)
+* lagoon-core chart [1.37.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.37.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release
diff --git a/docs/deprecations/2.17.0.md b/docs/releases/2.17.0.md
similarity index 58%
rename from docs/deprecations/2.17.0.md
rename to docs/releases/2.17.0.md
index 9d0c486938..a74a2dd184 100644
--- a/docs/deprecations/2.17.0.md
+++ b/docs/releases/2.17.0.md
@@ -1,8 +1,19 @@
+#### Release Links
+* lagoon [v2.17.0](https://github.com/uselagoon/lagoon/releases/tag/v2.17.0)
+* lagoon-ui [core-v2.17.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.17.0)
+* lagoon-build-deploy [core-v2.17.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.17.0)
+* lagoon-core chart [1.41.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.41.0)
+* lagoon-remote chart [0.87.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.87.0)
 
-### Lagoon v2.17.0
+## Upgrades
 
-Release link: [https://github.com/uselagoon/lagoon/releases/tag/v2.17.0](https://github.com/uselagoon/lagoon/releases/tag/v2.17.0)
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
 
+## Deprecations
+
+### activestandby task image
 * This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
+### API Harbor support
 * Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
-* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
\ No newline at end of file
+### Harbor 2.1 and earlier support
+* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
diff --git a/docs/deprecations/2.18.0.md b/docs/releases/2.18.0.md
similarity index 66%
rename from docs/deprecations/2.18.0.md
rename to docs/releases/2.18.0.md
index 41859185cb..da9c8de177 100644
--- a/docs/deprecations/2.18.0.md
+++ b/docs/releases/2.18.0.md
@@ -1,11 +1,24 @@
+#### Release Links
+* lagoon [v2.18.0](https://github.com/uselagoon/lagoon/releases/tag/v2.18.0)
+* lagoon-ui [core-v2.18.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.18.0)
+* lagoon-build-deploy [core-v2.18.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.18.0)
+* lagoon-core chart [1.42.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.42.0)
+* lagoon-remote chart [0.88.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.88.0)
 
-### Lagoon v2.18.0
+## Upgrades
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
 
-release link: [https://github.com/uselagoon/lagoon/releases/tag/v2.18.0](https://github.com/uselagoon/lagoon/releases/tag/v2.18.0)
+## Deprecations
 
-* The standard drupal based tasks that Lagoon ships with (drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
-* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is becaues the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatability for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
+### In-built Drupal Tasks
+* The standard drupal based tasks that Lagoon ships with (Drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
+### setEnvironmentServices
+* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is because the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatibility for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
+### Core Registry variable
 * The value for `registry` which was previously required by the `lagoon-core` chart is no longer required. If you are using this, you will need to add it under the new `unauthenticatedRegistry` setting when installing `lagoon-remote` in the `lagoon-build-deploy` section of your values file. If you aren't using an actual registry and have the example `disabled-only-use-harbor-via-deploy-controller.invalid` value, then you do not need to do anything except you can now remove the `registry` setting from your core values file.
+### bytesUsed
 * The environment storage return field named `bytesUsed` is deprecated. The actual value stored is `kibibytes`. A new return field called `kibUsed` exists and should be used, the returned data is the same and both fields are still returned. `bytesUsed` will be removed in a future release, make any adjustments now to use `kibUsed`. This will be a breaking change in a future release.
+### addOrUpdateEnvironmentStorage
 * `addOrUpdateEnvironmentStorage` is deprecated, `addOrUpdateStorageOnEnvironment` is the replacement to use as it supports the updated input value for `kibUsed`. `addOrUpdateEnvironmentStorage` will be completely removed in a future release.
-* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.
\ No newline at end of file
+### activesystems
+* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.
diff --git a/docs/releases/policy.md b/docs/releases/policy.md
new file mode 100644
index 0000000000..5a3c2c3784
--- /dev/null
+++ b/docs/releases/policy.md
@@ -0,0 +1,22 @@
+## Upgrade Policy
+
+Our general policy is that you should upgrade to the latest version of each minor version before you upgrade to the latest version.
+
+You should check all upgrade requirements and deprecation notices for all versions as you upgrade.
+
+An example of this policy is as follows
+
+* Currently installed v2.13.0, planning to upgrade to v2.16.0
+  1. Upgrade to v2.14.2 (the latest 2.14.x release)
+  2. Upgrade to v2.15.4 (the latest 2.15.x release)
+  3. Upgrade to v2.16.0
+
+We may, from time to time, provide additional context to the upgrades listed in these pages.
+
+## Deprecation Policy
+
+As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
+
+Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases).
+
+We may, from time to time, provide additional context to the deprecations listed in these pages.
diff --git a/docs/releases/x.xx.x.md.tmpl b/docs/releases/x.xx.x.md.tmpl
new file mode 100644
index 0000000000..3163da5562
--- /dev/null
+++ b/docs/releases/x.xx.x.md.tmpl
@@ -0,0 +1,28 @@
+TEMPLATE FOR RELEASES - add/modify as required and save with release number
+
+#### Release Links
+* lagoon [vx.xx.x](https://github.com/uselagoon/lagoon/releases/tag/vx.xx.x)
+* lagoon-ui [core-vx.xx.x](https://github.com/uselagoon/lagoon-ui/releases/tag/core-vx.xx.x)
+* lagoon-build-deploy [core-vx.xx.x](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-vx.xx.x)
+* lagoon-core chart [x.xx.x](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-x.xx.0)
+* lagoon-remote chart [x.xx.x](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-x.xx.x)
+
+## Upgrades
+
+EITHER
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+OR
+This release was superseded, and the [x.xx.x](./x.xx.x.md) release is recommended to be installed instead.
+OR
+### Upgrade Heading
+Upgrade Text
+
+## Deprecations
+
+EITHER
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+OR
+This release was superseded, and the [x.xx.x](./x.xx.x.md) release is recommended to be installed instead.
+OR
+### Deprecation Heading
+Deprecation Text
diff --git a/docs/upgrades/2.10.0.md b/docs/upgrades/2.10.0.md
deleted file mode 100644
index cb3953c7b3..0000000000
--- a/docs/upgrades/2.10.0.md
+++ /dev/null
@@ -1,4 +0,0 @@
-### Upgrade to Lagoon v2.10.0
-You must upgrade to Lagoon v2.9.x before upgrading to v2.10.0.
-
-Ensure you read the [release notes](https://github.com/uselagoon/lagoon/releases/tag/v2.10.0) before upgrading to make sure you are aware of all the changes you may be required to do.
\ No newline at end of file
diff --git a/docs/upgrades/2.11.0.md b/docs/upgrades/2.11.0.md
deleted file mode 100644
index d6af9f6c94..0000000000
--- a/docs/upgrades/2.11.0.md
+++ /dev/null
@@ -1,5 +0,0 @@
-### Upgrade to Lagoon v2.11.0
-
-You must upgrade to Lagoon v2.10.0 before upgrading to v2.11.0.
-
-Ensure you read the [release notes](https://github.com/uselagoon/lagoon/releases/tag/v2.11.0) before upgrading to make sure you are aware of all the changes you may be required to do.
\ No newline at end of file
diff --git a/docs/upgrades/policy.md b/docs/upgrades/policy.md
deleted file mode 100644
index 812b5b7996..0000000000
--- a/docs/upgrades/policy.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Upgrade Policy
-
-Our general policy is that you should upgrade to each minor version before you upgrade to the latest version.
-
-You should check all upgrade requirements and deprecation notices for all versions as you upgrade.
-
-An example of our suggested policy is as follows
-
-* Currently installed v2.14.0, planning to upgrade to v2.17.0
-  1. Upgrade to v2.15.0
-  2. Upgrade to v2.16.0
-  3. Upgrade to v2.17.0
diff --git a/mkdocs.yml b/mkdocs.yml
index a98b439367..05f3d0550e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -161,8 +161,7 @@ nav:
   - Lagoon CLI: https://uselagoon.github.io/lagoon-cli/
   - Lagoon Sync: https://github.com/uselagoon/lagoon-sync
   - Client Libraries: other-tools/client-libraries.md
-- ... | upgrades/*
-- ... | deprecations/*
+- ... | releases/*
 
 theme:
   name: 'material'