Update versions and release documentation (16)

docs/conf.py

@@ -335,5 +335,6 @@
 # Add configuration for intersphinx mapping
 
 intersphinx_mapping = {
-    'starter-pack': ('https://canonical-example-product-documentation.readthedocs-hosted.com/en/latest', None)
+    'postgresql-14': ('https://canonical-charmed-postgresql.readthedocs-hosted.com/14/', None)
 }
+myst_url_schemes = ["http", "https", ]

docs/explanation/charm-versions/index.md

@@ -0,0 +1,44 @@
+# PostgreSQL major versions
+
+Charmed PostgreSQL is available in multiple versions to support different deployment requirements and lifecycle stages. It is shipped in the following [tracks](https://documentation.ubuntu.com/juju/3.6/reference/charm/#track):
+
+
+| Charm name              | Charmhub channel | Type   | Status                                                            |
+| ----------------------- | ---------------- | ------ | ----------------------------------------------------------------- |
+| PostgreSQL 16           | `16/stable`      | modern | ![check] Latest version - new features are released here          |
+| PostgreSQL 14           | `14/stable`      | modern | ![check] In maintenance mode - bug fixes and security updates only |
+| Legacy PostgreSQL charm | `latest/stable`  | legacy | ![cross] Deprecated                                               |
+
+## Legacy vs. modern
+
+There are two [generations](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) of charms stored under the same charm name `postgresql`. In these docs, we refer to them as "legacy" and "modern". 
+
+Legacy charm (deprecated)
+: Also known as a [Reactive charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm). Found in the Charmhub channel `latest/stable`.
+: Provided `db` and `db-admin` endpoints for the `pgsql` interface.
+
+Modern charm
+: Also known as an [Ops charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm). Found in the Charmhub channels `14/stable` and `16/stable`.
+: `14/stable` provides legacy endpoints and new `database` endpoint for the `postgresql_client` interface.
+: `16/stable` **does not** provide legacy endpoints - only the new `database` `database` endpoint for the `postgresql_client` interface.
+
+```{seealso}
+* [](/explanation/charm-versions/legacy-charm)
+* [](/explanation/charm-versions/modern-charm)
+* [](/explanation/interfaces-and-endpoints)
+```
+
+<!--Links-->
+
+[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303
+[check]: https://img.icons8.com/color/20/checkmark--v1.png
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:glob:
+:hidden:
+
+Legacy charm <legacy-charm>
+Modern charm <modern-charm>
+```

docs/explanation/charm-versions/legacy-charm.md

@@ -0,0 +1,18 @@
+# Legacy PostgreSQL charm
+
+The legacy PostgreSQL charm is a [Reactive charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) in the **now deprecated** Charmhub channel `latest/stable`. 
+
+The PostgreSQL 16 charm does not support the same endpoints as the legacy charm. To migrate from legacy to PostgreSQL 16, you must implement the modern `database` endpoint for the `postgresql_client` interface on your charm.
+
+To read more about implementing compatible endpoints, see: [](/how-to/development/integrate-with-your-charm)
+
+To read more about the legacy charm see the {doc}`PostgreSQL 14 documentation <postgresql-14:explanation/charm-versions/legacy-charm>`.
+
+## How to report issues and contact authors
+
+The legacy charm (from `latest/stable`) is stored on [Launchpad](https://git.launchpad.net/postgresql-charm/). Report legacy charm issues [here](https://bugs.launchpad.net/postgresql-charm).
+
+The modern charms are stored on GitHub: [PostgreSQL 14 branch](https://github.com/canonical/postgresql-operator/tree/main) and [PostgreSQL 16 branch](https://github.com/canonical/postgresql-operator/tree/16/edge) . Report modern charm issues [here](https://github.com/canonical/postgresql-operator/issues/new/choose).
+
+Do you have questions? [Contact us](/reference/contacts)!
+

docs/explanation/charm-versions/modern-charm.md

@@ -0,0 +1,109 @@
+# Modern PostgreSQL charm
+
+Modern PostgreSQL charms are [Ops charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm) released in the Charmhub channels `14/` and `16/`. 
+
+Both modern charms provide the `database` endpoint for the `postgresql_client` interface.
+
+PostgreSQL 14 (track `14/`) additionally provides `db` and `db-admin` endpoints for the legacy `pgsql` interface, and supports migration from the legacy charm.
+
+PostgreSQL 16 (track `16/`) does not provide legacy endpoints.
+
+```{note}
+You are currently viewing the documentation for **Charmed PostgreSQL 16**.
+
+To switch between versions, use the small rectangular menu at the bottom right corner of the page.
+```
+
+## PostgreSQL 16
+
+**Latest stable version** with active feature development.
+
+* **Base:** Ubuntu 24.04 LTS (Noble)
+* **Supported architectures:** `amd64`, `arm64`
+* **Channel:** `16/stable` (latest development available for testing in `16/edge`)
+* **Juju version:** Requires Juju 3.6+ LTS
+* **Support status:** ![check] Active development and full support
+
+### New features
+
+* [**Juju spaces**](/how-to/deploy/juju-spaces) - Enhanced networking capabilities for complex deployment scenarios
+* [**Juju user secrets**](https://documentation.ubuntu.com/juju/latest/reference/secret/index.html#user-secret) - Secure management of the charm's [internal passwords](/how-to/manage-passwords)
+* **Improved** [**security hardening**](/explanation/security/index) - Enhanced security posture and best practices
+* **TLS v4 library migration**
+  * New endpoints `client-certificates` and `peer-certificates` 
+  * Endpoint `peer-interfaces` uses TLS by default
+  * See all endpoints on [Charmhub](https://charmhub.io/postgresql/integrations?channel=16/stable)
+* [**Timescale Community Edition**](/how-to/enable-plugins-extensions/enable-timescaledb) replaces Timescale Apache 2
+* **Improved** [**built-in roles**](/explanation/roles) - Enhanced role-based access control system
+* **New** **refresh process** for in-place upgrades
+
+### Deprecated or removed
+
+Important changes to keep in mind when migrating from 14 to 16:
+
+* **Legacy interface `psql`** - Endpoints `db` and `db-admin` are no longer supported
+  * See [](/explanation/interfaces-and-endpoints) for current supported interfaces
+* **Support for Juju < `v3.6` removed**
+  * Charmed PostgreSQL 16 requires Juju `3.6+ LTS` due to [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html) support
+* **Juju actions `get-password` and `set-password` removed**
+  * Replaced by [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html) for enhanced security
+* **[Timescale Apache 2 edition](https://docs.timescale.com/about/latest/timescaledb-editions/) replaced**
+  * Now uses [Timescale Community edition](https://docs.timescale.com/about/latest/timescaledb-editions/)
+* **Charm action `set-tls-private-key` removed**
+  * Will be re-introduced as Juju User Secrets in future releases
+* **Charm actions renamed for consistency:**
+  * `pre-upgrade-check` → `pre-refresh-check`
+  * `resume-upgrade` → `resume-refresh`
+  * Changes align with `juju refresh` terminology
+* **Charm endpoint `certificates` split into separate endpoints:**
+  * `client-certificates` - For client certificate management
+  * `peer-certificates` - For peer-to-peer certificate management
+
+For detailed information about all PostgreSQL 16 releases, see the [Releases page](/reference/releases).
+
+## PostgreSQL 14
+
+**Maintenance mode** with bug fixes and security updates only.
+
+* **Base:** Ubuntu 22.04 LTS (Jammy)
+* **Supported architectures:** `amd64`, `arm64`
+* **Channel:** `14/stable`
+* **Juju version:** Partially compatible with older Juju versions down to 2.9
+* **Support status:** 🔧 Bug fixes and security updates only
+
+### Features
+
+* [**Deployment on multiple cloud services**](/how-to/deploy/index), including Sunbeam, MAAS, AWS, GCE, and Azure
+* [**Juju storage**](/how-to/deploy/juju-storage) - Flexible storage configuration options
+* [**Back up and restore**](/how-to/back-up-and-restore/index), including point-in-time recovery
+* [**COS integration**](/how-to/monitoring-cos/index) - Enable observability tools like Grafana, Loki, Tempo, and Parca
+* [**TLS integration**](/how-to/enable-tls)
+* [**LDAP integration**](/how-to/enable-ldap) - Centralised authentication for PostgreSQL clusters 
+* [**`amd64` and `arm64`architecture** support](/reference/system-requirements)
+
+For detailed information about all PostgreSQL 14 releases, see the {doc}`PostgreSQL 14 Releases page <postgresql-14:reference/releases>`
+
+## Choosing a version
+
+| Version | Support Status | Base | Juju Version | Key Features |
+|---------|----------------|------|--------------|-------------|
+| **PostgreSQL 16** | ![check] Active development | Ubuntu 24.04 LTS | 3.6+ LTS | Latest PostgreSQL and Juju features, enhanced security |
+| **PostgreSQL 14** | 🔧 Maintenance mode | Ubuntu 22.04 LTS | 2.9+ | Core database features, stable platform |
+| **Legacy** | ![cross] Deprecated | Older base | Legacy versions | Not recommended |
+
+* **For new deployments**: Use **PostgreSQL 16** for the latest features and long-term support
+* **For existing PostgreSQL 14 deployments**: Continue using PostgreSQL 14 or plan migration to 16
+* **For legacy charm users**: Migrate to PostgreSQL 14 as soon as possible
+
+<!-- Links -->
+
+[PostgreSQL 16]: https://charmhub.io/postgresql?channel=16/beta
+[PostgreSQL 14]: https://charmhub.io/postgresql?channel=14/stable
+[Legacy PostgreSQL charm]: https://charmhub.io/postgresql?channel=latest/stable
+
+[Version 16 Release Notes]: /reference/version-16-release-notes
+[release notes]: /reference/releases
+[legacy charm explanation page]: /explanation/charm-versions/legacy-charm
+
+[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303
+[check]: https://img.icons8.com/color/20/checkmark--v1.png

docs/explanation/index.md

@@ -9,7 +9,7 @@ Additional context about key concepts behind the PostgreSQL charm, including des
 
 Architecture <architecture>
 Interfaces and endpoints <interfaces-and-endpoints>
-Legacy charm <legacy-charm>
+Charm versions <charm-versions/index>
 ```
 
 ## Operational concepts

docs/explanation/interfaces-and-endpoints.md

@@ -39,7 +39,7 @@ Find all details about default and extra DB user roles in "[Charm Users explanat
 ```{note}
 Legacy relations are deprecated and will be discontinued on future releases. Their usage should be avoided. 
 
-Check the legacy interfaces implementation limitations in [](/explanation/legacy-charm)"
+Check the legacy interfaces implementation limitations in [](/explanation/charm-versions/legacy-charm)"
 ```
 
 ### Legacy `pgsql` interface (`db` and `db-admin` endpoints):

docs/how-to/deploy/juju-storage.md

@@ -4,7 +4,7 @@ Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju
 
 [Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/stable) supports multiple storage types: `archive`, `data`, `logs` and `temp`.
 
-The [legacy PostgreSQL charm](/explanation/legacy-charm) in track [`latest`](https://charmhub.io/postgresql?channel=latest/stable) does **not** support the Juju storage abstraction.
+The [legacy PostgreSQL charm](/explanation/charm-versions/legacy-charm) in track [`latest`](https://charmhub.io/postgresql?channel=latest/stable)" does **not** support the Juju storage abstraction.
 
 ## Check Juju storage details
 

docs/how-to/development/integrate-with-your-charm.md

@@ -2,15 +2,15 @@
 
 Charmed PostgreSQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with PostgreSQL.
 
+(check-supported-interfaces)=
 ## Check supported interfaces
 First, we recommend that you check [the supported interfaces](/explanation/interfaces-and-endpoints) of the current charm. You have the option to use modern (preferred) or legacy interfaces. 
 
 Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs).**
 
-Legacy charm details are described [here](/explanation/legacy-charm).
+Legacy charm details are described [here](/explanation/charm-versions/legacy-charm).
 
 ## Integrate your charm with PostgreSQL
-> See also: [Juju documentation | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/)
 
 **For a detailed tutorial** about integrating your charm with the PostgreSQL charm, refer to [Juju | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql). 
 
@@ -19,12 +19,18 @@ Legacy charm details are described [here](/explanation/legacy-charm).
 *  [juju-sdk-tutorial-k8s](https://github.com/canonical/juju-sdk-tutorial-k8s/tree/04_integrate_with_psql) - the branch `04_integrate_with_psql` describes integration with Charmed PostgreSQL K8s 
 * [How to migrate Nextcloud to new PostgreSQL (vm-charms)](https://discourse.charmhub.io/t/nextcloud-postgresql-how-to-migrate-nextcloud-to-new-postgresql-vm-charms/10969) guide
 
+```{seealso}
+[Juju documentation | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/)
+```
+
 ## Troubleshooting & testing
+
 * To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm)
 * To troubleshoot PostgreSQL, check the [Troubleshooting](/reference/troubleshooting/index) reference
 * To test PostgreSQL and other charms, check the [Testing](/reference/software-testing) reference
 
 ## FAQ
+
 **Does the requirer need to set anything in relation data?**
 >It depends on the interface. Check the `postgresql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md).