(wip) apply some feedback

Author: a-velasco

docs/how-to/refresh/index.md

@@ -1,29 +1,38 @@
 # Refresh (upgrade)
 
-A charm **refresh** is any change to the version of a charm, and/or its {term}`workload`. 
+Charmed PostgreSQL supports minor {term}`in-place` {term}`refresh` via the [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command.
 
-Charmed PostgreSQL supports minor in-place {term}`upgrades <upgrade>` via the [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command.
+```{admonition} Emergency stop button
+:class: attention
+Use `juju config appname pause-after-unit-refresh=all` to halt an in-progress refresh
+```
 
-## Supported refresh types
+## Supported refreshes
 
-This charm **can only be upgraded to a higher version**. It cannot be {term}`downgraded <downgrade>` to a lower version.
+**Minor in-place {term}`upgrade`** between stable releases. 
+E.g. PostgreSQL 16.9 is upgraded to 16.10
 
-The charm version can only be lowered in the case of an ongoing refresh that needs to {term}`roll back <rollback>` to its {term}`original version` due to a failure.
+> See [How to perform a minor upgrade](/how-to/refresh/minor-upgrade)
 
-```{seealso}
-* [How to perform a minor upgrade](/how-to/refresh/minor-upgrade)
-* [How to perform a minor rollback](/how-to/refresh/minor-rollback)
-```
+**Minor in-place {term}`rollback`** between stable releases. 
+E.g. An upgrade from PostgreSQL 16.9 -> 16.10 fails, so a rollback is triggered to take all units from 16.10 back to 16.9.
 
-## Supported versions
+> See [How to perform a minor rollback](/how-to/refresh/minor-rollback)
 
-This charm **only supports minor version upgrades**, e.g. 16.9 --> 16.10.
+<!-- TODO: Add when new stable: * Minor in-place upgrade from Revision X to Y -->
 
-[Contact us](/reference/contacts) if you want to migrate from Charmed PostgreSQL 14 to 16
+Check all available Charmed PostgreSQL 16 versions in [](/reference/releases).
+
+## Non-supported refreshes
+* Minor in-place {term}`downgrade` from PostgreSQL 16.10 to 16.9
+* Major in-place {term}`upgrade` from PostgreSQL 14 to 16
+* Major in-place {term}`downgrade` from PostgreSQL 16 to 14
+* Any refresh involving non-stable versions (e.g. 16/edge)
+
+The actions listed above must be performed as {term}`out of place` upgrades.
+
+<!--TODO: When ready, point to 14-16 migration guide -->
 
-```{seealso}
-* [Charmed PostgreSQL 16 versions](/reference/releases)
-```
 
 ```{toctree}
 :titlesonly:

docs/how-to/refresh/minor-rollback.md

@@ -4,12 +4,6 @@ After running `juju refresh`, if there are any version incompatibilities in char
 
 Even if the underlying PostgreSQL cluster continues to work, it’s important to roll back the charm to the {term}`original version` so that an update can be attempted after further inspection of the failure.
 
-```{attention}
-Only trigger a rollback if the refresh has explicitly failed and cannot continue. Do not initiate a rollback while the refresh process is still running.
-
-<!--TODO: examples-->
-```
-
 ---
 
 ## Initiate rollback

docs/how-to/refresh/minor-upgrade.md

@@ -1,40 +1,39 @@
 # Perform a minor upgrade
 
-A minor upgrade is a {term}`refresh` from one workload version to a higher one within the same major version (e.g. PostgreSQL 14.12 --> PostgreSQL 14.15)
-
-The refresh process boils down to:
-* Running a pre-refresh check to ensure your deployment can undergo a safe upgrade process
-* Running the refresh command to initiate the process
-* Monitoring and following UI instructions
+A minor {term}`in-place` {term}`upgrade` is a {term}`refresh` from one {term}`workload` version to a higher one, within the same major version (e.g. PostgreSQL 14.12 --> PostgreSQL 14.15)
 
 Once in the refresh is in progress, the UI will clearly indicate what is happening to each unit, and what actions are required from the user to continue the process or roll back in case of a problem.
 
+If your upgrade has failed, see [How to perform a minor rollback](/how-to/refresh/minor-rollback)
+
 ```{seealso}
-* [How to perform a minor rollback](/how-to/refresh/minor-rollback)
+
 * [All Charmed PostgreSQL minor versions](/reference/releases)
-* [](/how-to/back-up-and-restore/create-a-backup)
 * [Developer docs for charm-refresh](https://canonical-charm-refresh.readthedocs-hosted.com/latest/)
     * [`pause_after_unit_refresh` documentation](https://canonical-charm-refresh.readthedocs-hosted.com/latest/user-experience/config/#pause-after-unit-refresh)
 ```
 
-
 ## Precautions
 
 Below are some strongly recommended precautions before refreshing to ensure minimal service disruption:
 
 **Make sure to have a [backup](/how-to/back-up-and-restore/create-a-backup) of your data.**
 
-**Do not perform operations that modify your cluster while refreshing.**
+We recommend testing the integrity of your backup by performing a test [restore](/how-to/back-up-and-restore/restore-a-backup).
+
+**Avoid operations that modify your cluster while refreshing.**
 
 Concurrency with other operations is not supported, and it can lead the cluster to inconsistent states.
 
 ```{dropdown} Examples
 Avoid operations such as (but not limited to) the following:
 
-* Adding or removing units
+* Adding or removing units - unless it is necessary for recovery
 * Creating or destroying new relations
 * Changes in workload configuration
 * Upgrading other connected/related/integrated applications simultaneously
+
+[Contact us](/reference/contacts) if you have questions about performing operations during refresh.
 ```
 
 **Integrate with [Charmed PgBouncer](https://charmhub.io/pgbouncer).** 
@@ -44,9 +43,7 @@ This will ensure minimal service disruption, if any.
 (pre-refresh-check)=
 ## Pre-refresh check
 
-The `pre-refresh-check` action checks that a refresh is possible and will switch the primary, if necessary, for a safe upgrade process.
-
-This check happens automatically when you run `juju refresh`, but we recommend running it manually before scheduling a maintenance window for the refresh operation.
+The [`pre-refresh-check`](https://canonical-charm-refresh.readthedocs-hosted.com/latest/user-experience/actions/#pre-refresh-check) action checks that the application is healthy and ready to refresh (e.g. no other operations are running).   
 
 Run a pre-refresh check against the leader unit:
 
@@ -62,26 +59,21 @@ Copy down the rollback command from the action output in case a rollback is need
 
 ## Initiate refresh
 
-The following command will refresh the charm to the latest version in the channel you originally deployed your application from, e.g. `16/stable`:
+The following command will refresh the charm to the latest version in the channel you originally deployed your application from:
 
 ```shell
 juju refresh postgresql
 ```
 
-To refresh your charm to the latest version of a specific channel or track, use the `--channel` flag. For example:
-
-```shell
-juju refresh postgresql --channel 16/edge
-```
+It is expected for the Juju agents to enter a temporary `failed` state. 
 
-Units will be refreshed one by one based on role: first the `replica` units, then `sync-standby`, and lastly the `leader` unit. 
+Units will then be refreshed one by one based on role:
+1. `replica` units
+2. `sync-standby`
+3. `leader` unit.
 
 If there are any version incompatibilities in charm revisions, dependencies, or any other unexpected failure in the upgrade process, the process will halt and enter a failure state.
 
-```{attention}
-Only trigger a rollback if the refresh has explicitly failed and cannot continue. <!--TODO: examples + clarify if you can rollback when refresh is healthy but paused waiting for resume-refresh -->
-```
-
 ## Resume refresh
 
 If the [`pause_after_unit_refresh`](https://charmhub.io/postgresql/configurations?channel=16/edge#pause_after_unit_refresh) config option on your PostgreSQL application is set to `first` (default) or `all`, you'll need to monitor and manually resume the refresh when one or more units have finished refreshing individually.

docs/reference/glossary.md

@@ -28,4 +28,10 @@ workload
 
 original version
     Workload and/or charm version of all units before initiating a refresh process
+
+in-place
+    TODO
+    
+out-of-place
+    <!-- https://canonical-charm-refresh.readthedocs-hosted.com/latest/add-to-charm/is-this-for-you/ -->
 ```

docs/reference/releases.md

@@ -1,3 +1,7 @@
+---
+relatedlinks: "[Charm&#32risk](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk)"
+---
+
 # Releases
 
 Charmed PostgreSQL 16 supports all [features listed in PostgreSQL 14](https://canonical-charmed-postgresql.readthedocs-hosted.com/14/reference/releases/#dependencies-and-supported-features).
@@ -6,25 +10,22 @@ Charmed PostgreSQL 16 supports all [features listed in PostgreSQL 14](https://ca
 |:---:|:---:|:---:|
 | [843, 844] | 16.9  | 3.6+  |
 
-To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk).
+See all release notes on [GitHub](https://github.com/canonical/postgresql-operator/releases).
+
+## How to refresh (upgrade)
+
+Charmed PostgreSQL supports **minor in-place upgrades**. See [](/how-to/refresh/index) for more information.
 
-To see all releases and commits, check the [Charmed PostgreSQL Releases page on GitHub](https://github.com/canonical/postgresql-operator/releases).
+[Contact us](/reference/contacts) if you are interested in migrating from PostgreSQL 14 to 16.
 
 ## Architecture and base
 
 Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#charm-revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions.
 
 If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture.
 
-```{caution}
-If you deploy with the `--revision` flag, **you must make sure the revision matches your base and architecture**. 
-
-Check the tables below, or use [`juju info`](https://juju.is/docs/juju/juju-info).
-```
-
-## Plugins/extensions
+<!--TODO: Move to explanation -->
 
-For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/reference/plugins-extensions).
 
 <!-- LINKS -->
 [843, 844]: https://github.com/canonical/postgresql-operator/releases/tag/v16%2F1.59.0