Sync docs from Discourse (#365)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
canonical · Oct 7, 2024 · d973b19 · d973b19
1 parent 3b896fd
commit d973b19
Show file tree

Hide file tree

Showing 5 changed files with 153 additions and 31 deletions.
diff --git a/docs/how-to/h-upgrade-minor.md b/docs/how-to/h-upgrade-minor.md
@@ -7,12 +7,17 @@ We strongly recommend to **NOT** perform any other extraordinary operations on C
 3. Changes in workload configuration
 4. Upgrading other connected/related/integrated applications simultaneously
 
-The concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
+Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
 
-> **:warning: NOTE:** Make sure to have a [Charmed PostgreSQL backups](/t/9683) of your data when running any type of upgrades.
+[note type="caution"]
+Make sure to have a [Charmed PostgreSQL backups](/t/9683) of your data when running any type of upgrades.
+[/note]
 
-> **:warning: TIP:** The "PgBouncer" upgrade should follow first, before "Charmed PostgreSQL" upgrade!!!
+[note]
+The "PgBouncer" upgrade should follow first, before "Charmed PostgreSQL" upgrade!!!
+[/note]
 
+---
 ## Minor upgrade steps
 
 1. **Collect** all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do NOT skip this step, it is better safe the sorry!
@@ -25,8 +30,9 @@ The concurrency with other operations is not supported, and it can lead the clus
 8. Post-upgrade **Check**. Make sure all units are in the proper state and the cluster is healthy.
 
 ## Step 1: Collect
-
-> **:information_source: NOTE:** The step is only valid when deploying from charmhub. If the [local charm](https://juju.is/docs/sdk/deploy-a-charm) deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for rollback.
+[note]
+The step is only valid when deploying from charmhub. If the [local charm](https://juju.is/docs/sdk/deploy-a-charm) deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for rollback.
+[/note]
 
 The first step is to record the revision of the running application, as a safety measure for a rollback action. You can find the revisions of the deployed Charmed PostgreSQL and PgBouncer applications with `juju status`.  Store them safely to use in case of rollback!
 <!--
@@ -77,8 +83,8 @@ juju refresh postgresql --channel 8.0/edge
 
 juju refresh postgresql --revision=89
 ```
-[note type="caution"]
-Important notes:
+[note]
+Note that:
 * The PostgreSQL upgrade will execute only on the **highest ordinal unit**. 
 * It is expected to have some status changes during the process: `waiting`, `maintenance`, `active`. **Do not trigger `rollback` procedure during the running `upgrade` procedure.** Make sure `upgrade` has failed or stopped and cannot be fixed/continued before triggering a rollback!
 * The unit should recover shortly after, but the time can vary depending on the amount of data written to the cluster while the unit was not part of the cluster. **Large installations might take some extra time to recover.**

diff --git a/docs/overview.md b/docs/overview.md
@@ -8,6 +8,13 @@ PostgreSQL is a powerful, open source object-relational database system that use
 
 The PgBouncer operator comes in two flavours to deploy and operate PostgreSQL on [physical/virtual machines](https://github.com/canonical/pgbouncer-operator) and [Kubernetes](https://github.com/canonical/pgbouncer-operator). Both offer identical features and simplifies deployment, scaling, configuration and management of PgBouncer in production at scale in a reliable way.
 
+## In this documentation
+
+| | |
+|--|--|
+|  [Tutorials]()</br>  Get started - a hands-on introduction to using PgBouncer operator for new users </br> |  [How-to guides]() </br> Step-by-step guides covering key operations and common tasks |
+| [Reference](https://charmhub.io/pgbouncer/actions) </br> Technical information - specifications, APIs, architecture | [Explanation]() </br> Concepts - discussion and clarification of key topics  |
+
 ## Project and community
 
 This PgBouncer charm is an official distribution of PgBouncer. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
@@ -17,12 +24,7 @@ This PgBouncer charm is an official distribution of PgBouncer. It’s an open-so
 - Explore [Canonical Data Fabric solutions](https://canonical.com/data)
 -  [Contacts us]() for all further questions
 
-## In this documentation
 
-| | |
-|--|--|
-|  [Tutorials]()</br>  Get started - a hands-on introduction to using PgBouncer operator for new users </br> |  [How-to guides]() </br> Step-by-step guides covering key operations and common tasks |
-| [Reference](https://charmhub.io/pgbouncer/actions) </br> Technical information - specifications, APIs, architecture | [Explanation]() </br> Concepts - discussion and clarification of key topics  |
 
 # Navigation
 
@@ -53,8 +55,7 @@ This PgBouncer charm is an official distribution of PgBouncer. It’s an open-so
 | 3 | h-enable-monitoring | [Monitor (COS)](/t/12308) |
 | 3 | h-enable-tracing | [Tracing (COS)](/t/14788) |
 | 1 | reference | [Reference]() |
-| 2 | r-releases-group | [Release Notes]() |
-| 3 | r-releases | [All releases](/t/12285) |
+| 2 | r-releases | [Release Notes](/t/12285) |
 | 3 | r-revision-394-397 | [Revision 394-397](/t/15379) |
 | 3 | r-revision-278-281 | [Revision 278-281](/t/14853) |
 | 3 | r-revision-254-257 | [Revision 254-257](/t/14666) |

diff --git a/docs/reference/r-releases.md b/docs/reference/r-releases.md
@@ -1,23 +1,134 @@
 # Release Notes
 
-Here you will find release notes for the main revisions of this charm that are available in Charmhub [channels](https://juju.is/docs/sdk/channel):
+This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release. To learn more about the different release tracks, see the [Juju documentation about risk levels](https://juju.is/docs/juju/channel?#heading--risk).
 
-* **`stable`**: production-ready releases
-* **`candidate`, `beta`, `edge`** : [risk channels](https://juju.is/docs/sdk/channel#heading--risk) - new and experimental features. Not recommended for production.
+To see all releases and commits, check the [Charmed PgBouncer Releases page on GitHub](https://github.com/canonical/pgbouncer-operator/releases).
 
-## Revisions:
+## Dependencies and supported features
 
-|  Channel  | amd64 | arm64 |
-|---------:|:-----:|:-----:|
-| `1/stable`   | [396 (`jammy`) / 395 (`focal`)](/t/14853?channel=1/stable) |   [397 (`jammy`) / 394 (`focal`)](/t/14853?channel=1/stable)   |
-|           | [278 (`jammy`) / 279 (`focal`)](/t/14853?channel=1/stable) |   [280 (`jammy`) / 281 (`focal`)](/t/14853?channel=1/stable)   |
-|           | [256 (`jammy`) / 255 (`focal`)](/t/14666?channel=1/stable) |   [257 (`jammy`) / 254 (`focal`)](/t/14666?channel=1/stable)   |
-|           | [174 (`jammy`) / 175 (`focal`)](/t/14069?channel=1/stable) |   [173 (`jammy`) / 176 (`focal`)](/t/14069?channel=1/stable)   |
-|           | [88 (`jammy`) / 89 (`focal`)](/t/13126?channel=1/stable) |   -   |
-|           | [81 (`jammy`) / 80 (`focal`)](/t/12766?channel=1/stable) |   -   |
-|           | [76 (`jammy`) / 77 (`focal`)](/t/12286?channel=1/stable) |   -   |
+For each release, this table shows:
 
+* The PgBouncer version packaged inside
+* The minimum Juju version required to reliably operate **all** features of the release
+  > This charm still supports older versions of Juju 2.9. See the [system requirements](/t/12307) for more details
+* Support for specific features
+
+| Release| PgBouncer version | Juju version | [TLS encryption](/t/12310) | [COS monitoring](/t/12308) | [Minor version upgrades](/t/12317) |
+|:---:|:---:|:---:|:---:|:---:|:---:|
+|[394], [395], [396], [397]| `1.21.0` | `3.4.5+` | ![check] | ![check] | ![check]
+|[278], [279], [280], [281]| `1.21.0` | `3.4.5+` | ![check] | ![check] | ![check]
+|[254], [255], [256], [257]| `1.21.0` | `3.1.8+` | ![check] | ![check] | ![check]
+|[173], [174], [175], [176]| `1.21.0` | `3.1.8+` | ![check] | ![check] | ![check]
+|[88], [89] | `1.21.0` | `3.1.7+`| | ![check] | ![check]
+|[80], [81] | `1.21.0` | `3.1.6+`| | ![check] | ![check]
+|[76], [77]| `1.18.0` | `3.1.6+` | | ![check] | ![check]
+
+## Architecture and base
+
+Due to the [subordinate](https://juju.is/docs/sdk/charm-taxonomy#heading--subordinate-charms) nature of this charm, several [revisions](https://juju.is/docs/sdk/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.
+
+> If you deploy a specific revision, **you must make sure it matches your base and architecture** via the tables below or with [`juju info`](https://juju.is/docs/juju/juju-info).
+
+### Release 394-397 (`1/stable`)
+| Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:-----:|:--------:|:--------:|:-----:|:-----:|
+| [394] |          | ![check] | ![check] |          |
+| [395] | ![check] |          | ![check] |          |
+| [396] | ![check] |          |          | ![check] |
+| [397] |          | ![check] |          | ![check] |
+
+[details=Release 278-281]
+
+| Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:-----:|:--------:|:--------:|:-----:|:-----:|
+| [278] | ![check] |          |          | ![check] |
+| [279] | ![check] |          | ![check] |          |
+| [280] |          | ![check] |          | ![check] |
+| [281] |          | ![check] | ![check] |          |
+
+[/details]
+
+[details=Release 254-257]
+
+| Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:-----:|:--------:|:--------:|:-----:|:-----:|
+| [254] |          | ![check] | ![check] |          |
+| [255] | ![check] |          | ![check] |          |
+| [256] | ![check] |          |          | ![check] |
+| [257] |          | ![check] |          | ![check] |
+
+[/details]
+
+[details=Release 173-176]
+
+| Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:-----:|:--------:|:--------:|:-----:|:-----:|
+| [173] |          | ![check] |          | ![check] |
+| [174] | ![check] |          |          | ![check] |
+| [175] | ![check] |          | ![check] |          |
+| [176] |          | ![check] | ![check] |          |
+
+[/details]
+
+[details=Release 88-89]
+
+| Revision | amd64 | arm64 | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:----:|:--------:|:--------:|:-----:|:-----:|
+| [89] | ![check] |          | ![check] |          |
+| [88] | ![check] |          |          | ![check] |
+
+[/details]
+
+[details=Release 80-81]
+
+| Revision | amd64 | arm64 | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:----:|:--------:|:--------:|:-----:|:-----:|
+| [81] | ![check] |          |          | ![check] |
+| [80] | ![check] |          | ![check] |          |
+
+[/details]
+
+[details=Release 76-77]
+
+| Revision | amd64 | arm64 | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:----:|:--------:|:--------:|:-----:|:-----:|
+| [77] | ![check] |          | ![check] |          |
+| [76] | ![check] |          |          | ![check] |
+
+[/details]
+
+<br>
 
 [note]
-Due to the [subordinate nature](https://juju.is/docs/sdk/charm-taxonomy#heading--subordinate-charms) of this charm, several [revisions](https://juju.is/docs/sdk/revision) have been released simultaneously to the different [bases/series](https://juju.is/docs/juju/base) using the same charm code.
-[/note]
+ Our release notes are an ongoing work in progress. If there is any additional information about releases that you would like to see or suggestions for other improvements, don't hesitate to contact us on [Matrix ](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) or [leave a comment](https://discourse.charmhub.io/t/pgbouncer-reference-release-notes/12285).
+[/note]
+
+<!--LINKS-->
+[394]: /t/15379
+[395]: /t/15379
+[396]: /t/15379
+[397]: /t/15379
+[394, 395, 396, 397]: /t/15379
+[278]: /t/14853
+[279]: /t/14853
+[280]: /t/14853
+[281]: /t/14853
+[254]: /t/14666
+[255]: /t/14666
+[256]: /t/14666
+[257]: /t/14666
+[173]: /t/14069
+[174]: /t/14069
+[175]: /t/14069
+[176]: /t/14069
+[89]: /t/13126
+[88]: /t/13126
+[81]: /t/12766
+[80]: /t/12766
+[77]: /t/12286
+[76]: /t/12286
+
+<!-- BADGES -->
+[check]: https://img.icons8.com/color/20/checkmark--v1.png
diff --git a/docs/reference/r-revision-394-397.md b/docs/reference/r-revision-394-397.md
@@ -24,7 +24,7 @@ where `<arch>` can be `amd64` or `arm64`.
 ---
 
 ## Highlights 
-* [Added HA cluster interface](https://charmhub.io/pgbouncer/integrations?channel=1/candidate#ha) ([PR #317](https://github.com/canonical/pgbouncer-operator/pull/317)) ([DPE-4066](https://warthogs.atlassian.net/browse/DPE-4066))
+* [Added HA cluster interface](https://charmhub.io/pgbouncer/integrations?channel=1/stable#ha) ([PR #317](https://github.com/canonical/pgbouncer-operator/pull/317)) ([DPE-4066](https://warthogs.atlassian.net/browse/DPE-4066))
 * Added URI to relation data (improves UX) ([PR #324](https://github.com/canonical/pgbouncer-operator/pull/324)) ([DPE-4683](https://warthogs.atlassian.net/browse/DPE-4683))
 * Add Unix socket access for principal charm (including strict SNAPs) ([PR #337](https://github.com/canonical/pgbouncer-operator/pull/337)) ([DPE-4683](https://warthogs.atlassian.net/browse/DPE-4683))
 

diff --git a/docs/reference/r-revision-89.md b/docs/reference/r-revision-89.md
@@ -1,9 +1,13 @@
-# PgBouncer revision 89
+# PgBouncer Revision 88/89
 
 <sub>February 21, 2024</sub>
 
 Dear community, we are excited to announce that the new Charmed PgBouncer operator is published in the `1/stable` [charmhub](https://charmhub.io/pgbouncer?channel=1/stable) channel for IAAS/VM.
 
+The PgBouncer charm releases multiple revisions simultaneously:
+* Revision 88 is built for `amd64` on Ubuntu 22.04 LTS
+* Revision 89 is built for `amd64` on Ubuntu 20.04 LTS
+
 ## New features
 
 * Juju 3.1.7 support (changes to Juju secrets)