From 1ea72438b3aee3e339d2713876cb025a30b80cdc Mon Sep 17 00:00:00 2001
From: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Date: Fri, 24 Oct 2025 16:42:10 +0300
Subject: [PATCH] docs: add upgrades page

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
---
 .wordlist.txt                       |  5 +++++
 web/docs/resource-name-migration.md | 11 ++++++-----
 web/docs/upgrades.mdx               | 16 ++++++++++++++++
 3 files changed, 27 insertions(+), 5 deletions(-)
 create mode 100644 web/docs/upgrades.mdx

diff --git a/.wordlist.txt b/.wordlist.txt
index e872a38..0569592 100644
--- a/.wordlist.txt
+++ b/.wordlist.txt
@@ -1,3 +1,4 @@
+nonResourceURLs
 AccessDenied
 AdditionalContainerArgs
 Akamai
@@ -49,6 +50,7 @@ SPDX
 SPDX
 SSL
 ServerRecoveryWindow
+ServiceAccount
 Slonik
 TLS
 TODO
@@ -106,6 +108,7 @@ involvedObject
 io
 isWALArchiver
 jq
+json
 jsonpath
 kb
 krew
@@ -131,7 +134,9 @@ recoverability
 repos
 retentionCheckInterval
 retentionPolicy
+roleRef
 rolebinding
+rolebindings
 rollout
 rpc
 sc
diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md
index 196396e..b5cd1b9 100644
--- a/web/docs/resource-name-migration.md
+++ b/web/docs/resource-name-migration.md
@@ -1,8 +1,8 @@
 ---
-sidebar_position: 41
+sidebar_position: 90
 ---
 
-# Resource Name Migration Guide
+# Resource name migration guide
 
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
@@ -64,7 +64,7 @@ Please refer to the [Installation](installation.mdx) section to deploy the new p
 :::danger Verify Resources Before Deletion
 **IMPORTANT**: The old resource names are generic and could potentially belong to other components in your cluster.
 
-**Before deleting each resource, verify it belongs to the barman plugin by checking:**
+**Before deleting each resource, verify it belongs to the Barman Cloud plugin by checking:**
 - For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups
 - For `metrics-*` roles: Check if they reference the `plugin-barman-cloud` ServiceAccount in `cnpg-system` namespace
 - For other roles: Look for labels like `app.kubernetes.io/name: plugin-barman-cloud`
@@ -79,7 +79,8 @@ You can add `--dry-run=client` to any `kubectl delete` command to preview what w
 removing anything.
 :::
 
-**Only proceed if you've verified these resources belong to the barman plugin (see warning above).**
+**Only proceed if you've verified these resources belong to the Barman Cloud
+plugin (see warning above).**
 
 For each resource below, first verify it belongs to barman, then delete it:
 
@@ -124,7 +125,7 @@ kubectl delete clusterrole metrics-reader
 The `metrics-reader` role is particularly dangerous to delete blindly. Many monitoring systems use this exact name. Only delete it if:
 1. You've verified it ONLY grants access to `/metrics`
 2. No other rolebindings reference it (checked with the jq command above)
-3. You're certain it was created by the barman plugin
+3. You're certain it was created by the Barman Cloud plugin
 
 If you're unsure, it's safer to leave it and let the new `barman-plugin-metrics-reader` role coexist with it.
 :::
diff --git a/web/docs/upgrades.mdx b/web/docs/upgrades.mdx
new file mode 100644
index 0000000..0ab9ddb
--- /dev/null
+++ b/web/docs/upgrades.mdx
@@ -0,0 +1,16 @@
+---
+sidebar_position: 25
+---
+
+# Upgrades
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+You can upgrade the plugin simply by installing the new version. Unless
+explicitly stated below or in the release notes, no special steps are required.
+
+## Upgrading to version 0.8.x from previous versions
+
+Version **0.8.0** introduces breaking changes to resource naming.
+To complete the upgrade successfully, follow the instructions in the
+["Resource name migration guide"](resource-name-migration.md).