Standard upgrades

src/current/_includes/common/upgrade/major-version-upgrade-cloud.md

@@ -2,20 +2,20 @@ This section shows how to perform a major-version upgrade for a cluster in Cockr
 
 1. Verify the cluster's current major version, and which versions it can be upgraded to:
     1. Sign into [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud).
-    1. From the **Clusters** page, find the cluster by name. If the cluster is in a folder, click the name of the folder to view its descendants. The cluster's major version and patch are shown in the **Version** column.
+    1. From the **Clusters** page, find the cluster by name. If the cluster is in a folder, click the name of the folder to find the cluster. The cluster's major version and patch are shown in the **Version** column.
 1. Check which upgrades are available to the cluster, if any.
 
     Beginning with v24.1, major versions alternate in type between Regular releases, which are required, and Innovation releases, which can be skipped.
 
     From a Regular release, you can upgrade to the next major release (an Innovation release) or the subsequent major release (another Regular release). From an Innovation release, you must upgrade to the next Regular release.
 
-    These releases also provide different support periods.
+    These releases also provide different support periods. For details on their support periods and which releases are Regular or Innovation releases, refer the [CockroachDB Cloud Support Policy]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy).
 
-    For details, refer the [CockroachDB Cloud Support Policy]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy).
+    To check whether major-version upgrades are available, click the three-dot **Actions** menu. If upgrades are available, **Upgrade major version** will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog.
 
-    To check whether major-version upgrades are available, click the three-dot **Action** menu. If upgrades are available, **Upgrade major version** will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog.
+    In CockroachDB {{ site.data.products.standard }}, if the cluster is set to upgrade major versions automatically, the Actions menu will not show the **Upgrade major version** option. To change this setting, refer to [Manage cluster upgrades]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades). 
 1. Before beginning a major-version upgrade, review its [Release notes]({% link releases/index.md %}), as well as the release notes for any skipped Innovation Releases. If any backward-incompatible changes or new features impact the cluster's workloads, you may need to make adjustments before beginning the upgrade.
-1. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is upgraded. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are upgraded one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node {{ site.data.products.advanced }} cluster will be unavailable while the cluster is upgraded and restarted. If necessary, prepare for the upgrade by communicating ahead of time with your users, and plan to begin the upgrade during a time when the impact on the cluster's workload will be minimized.
-1. To begin a major-version upgrade, go back to the dialog in the CockroachDB {{ site.data.products.cloud }} Console. If multiple upgrades are available, select the desired version. Review the details, then click **Start upgrade**. The dialog closes, and the **Version** column in the **Cluster List** page changes to **Upgrading**. When the upgrade has finished but has not yet been finalized, the **Version** column reports that the new version is **pending**.
+1. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster always remains fully available while it is upgraded. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are upgraded one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node {{ site.data.products.advanced }} cluster will be unavailable while the cluster is upgraded and restarted. If necessary, prepare for the upgrade by communicating ahead of time with your users, and plan to begin the upgrade during a time when the impact on the cluster's workload will be minimized.
+1. To begin a major-version upgrade, go back to the dialog in the CockroachDB {{ site.data.products.cloud }} Console. If multiple upgrades are available, select the desired version. Review the details, then click **Start upgrade**. After several seconds, the dialog closes, and the **Version** column in the **Cluster List** page changes to **Upgrading**, indicating the version to which you are upgrading the cluster. When the upgrade has finished but has not yet been finalized, the **Version** column reports that the new version is **pending finalization**.
 
-The upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). After the upgrade is finalized, the cluster can no longer be [rolled back](#roll-back-a-major-version-upgrade) to its previous major version. If you take no action, finalization occurs automatically after approximately 72 hours.
+The upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). After the upgrade is finalized, the cluster can no longer be [rolled back](#roll-back-a-major-version-upgrade) to its previous major version. If you take no action, finalization occurs automatically, after approximately 72 hours.

src/current/_includes/common/upgrade/overview.md

@@ -1,18 +1,60 @@
-CockroachDB offers the following types of upgrades:
+### Types of upgrades
 
-- **Major-version upgrades**: A [major-version upgrade]({% link releases/index.md %}#major-releases) moves a cluster from one major version of CockroachDB to another, such as from v24.2 to v24.3. A major-version upgrade may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade.
+- **Major-version upgrades**: A [major-version upgrade]({% link releases/index.md %}#major-releases), such as from v24.2 to v24.3, may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade.
 
 {% if page.path contains "cockroachcloud" %}
-    As of 2024, every second major version is an [Innovation release]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases). For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }}, innovation releases offer shorter support windows and can be skipped. Innovation releases are required for CockroachDB {{ site.data.products.basic }}, and are applied automatically.
+    As of 2024, there are four major versions per year, where every second release is an [innovation release]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases). For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }}, innovation releases offer shorter [support windows]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy) and can be skipped. For CockroachDB {{ site.data.products.basic }}, all major version upgrades are applied automatically as they become available, including innovation releases.
 {% else %}
     As of 2024, every second major version is an [Innovation release]({% link releases/release-support-policy.md %}#innovation-releases). Innovation releases offer shorter support windows and can be skipped.
 {% endif %}
-- **Patch upgrades**: A [patch upgrade]({% link releases/index.md %}#patch-releases) moves a cluster from one patch to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes.
+- **Patch upgrades**: A [patch upgrade]({% link releases/index.md %}#patch-releases) moves a cluster from one patch release to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes.
+
+    A major version of CockroachDB has two phases of patch releases: a series of **testing releases** (beta, alpha, and RC releases) followed by a series of **production releases** (vX.Y.0, vX.Y.1, and so on). A major version’s first production release (the .0 release) is also known as its GA release.
 
 {% if page.path contains "cockroachcloud" %}
-    Patch upgrades are automatically applied to CockroachDB {{ site.data.products.advanced }}, {{ site.data.products.standard }}, and {{ site.data.products.basic }} clusters.
+    For CockroachDB {{ site.data.products.advanced }}, {{ site.data.products.standard }}, and {{ site.data.products.basic }} clusters, all production patch releases for a major version are automatically applied, until the cluster is upgraded to a new major version.
 {% endif %}
 
-    A major version of CockroachDB has two phases of patch releases: a series of **testing releases** followed by a series of **production releases**. A major version’s initial production release is also known as its GA release. In the lead-up to a new major version's GA release, a series of Testing releases may be made available{% if page.path contains "cockroachcloud" %} to CockroachDB {{ site.data.products.advanced }} as Pre-Production Preview releases{% endif %} for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments. {% if page.path contains "cockroachcloud" %}If a cluster is upgraded to a Pre-Production Preview patch release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview releases, the initial GA release, and subsequent patch releases.{% else %}{{site.data.alerts.callout_info}}A cluster cannot be upgraded from an alpha binary of a prior release or from a binary built from the `master` branch of the CockroachDB source code.{{site.data.alerts.end}}{% endif %}
+    - In the lead-up to a new major version's GA, a series of beta and RC releases {% if page.path contains "cockroachcloud" %}may be made available to CockroachDB {{ site.data.products.advanced }} as Pre-Production Preview releases{% else %}are made available{% endif %} for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments.
+
+      {% if page.path contains "cockroachcloud" %}If a cluster is upgraded to a Pre-Production Preview release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview testing releases, the GA release, and subsequent production patch releases.{% else %}{{site.data.alerts.callout_info}}A cluster cannot be upgraded from an alpha binary of a prior release or from a binary built from the `master` branch of the CockroachDB source code.{{site.data.alerts.end}}{% endif %}
 
 To learn more about CockroachDB major versions and patches, refer to the [Releases Overview]({% link releases/index.md %}#overview).
+
+{% if page.path contains "cockroachcloud" %}
+### Upgrade differences across Cloud plans
+
+CockroachDB Cloud plan | Major version upgrades | Innovation releases
+---------------------- | ---------------------- | ----------------------
+Basic | Automatic | Required
+Standard | Automatic (default) or customer-initiated | Optional
+Advanced | Customer-initiated | Optional
+
+For all Cloud plans:
+
+- All major versions that are Regular releases (as opposed to Innovation releases) are required upgrades during the period in which they are supported.
+- Patch version upgrades occur automatically.
+{% endif %}
+### Compatible versions
+
+A cluster may always be upgraded to the next major release. Prior to v24.1, every major release is required. As of v24.1{% if page.path contains "cockroachcloud" %}, for CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }} clusters{% endif %}: 
+
+- If a cluster is running a major version that is labeled a Regular release, it can be upgraded to either the subsequent major version (an Innovation release) or the one after (the next Regular release, once it is available—skipping the Innovation release).
+
+- If a cluster is running a major version that is labeled an Innovation release, it can be upgraded only to the next Regular release.
+
+```mermaid
+graph LR
+    v241["v24.1<br/>Regular"] --> v242["v24.2<br/>Innovation"]
+    v241 --> v243["v24.3<br/>Regular"]
+    v242 --> v243
+    v243 --> v251["v25.1<br/>Innovation"]
+    v243 --> v252["v25.2<br/>Regular"]
+    v251 --> v252
+    v252 --> v253["v25.3<br/>Innovation"]
+    v252 --> v254["v25.4<br/>Regular"]
+    v253 --> v254
+
+    %% Styling
+    classDef default fill:#fff,stroke:#333,stroke-width:2px
+```

src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md

@@ -2,4 +2,4 @@ Before beginning a major-version upgrade:
 
 1. Review the cluster's [Metrics page]({% link cockroachcloud/metrics.md %}) to ensure that your cluster's compute and storage capacity is within acceptable values. The cluster must be able to tolerate some increase, in case the new version uses more resources for your workload. If any of these metrics is above healthy limits, consider increasing the cluster's resources before beginning your upgrade.
 1. {% include {{ site.current_cloud_version }}/backups/recommend-backups-for-upgrade.md %}
-1. Review the [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}), as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized.
+1. Review the [Release Notes for the major version]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions) to which you plan to upgrade, as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized.

src/current/_includes/common/upgrade/see-also-cloud.md

@@ -1,2 +1,3 @@
 - [Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %})
 - [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %})
+- Release notes for [additional supported versions]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions)

src/current/_includes/common/upgrade/upgrade-high-level.md

@@ -5,8 +5,12 @@ A major-version upgrade involves the following high-level steps, which are descr
 {% endif %}
 
 1. On one node at a time:
-    1. Replace the previous `cockroach` binary or container image with the new binary.
-    1. Restart the `cockroach` process and verify that the node has rejoined the cluster.
+    1. {% if page.path contains "cockroachcloud" %}The previous `cockroach` binary is replaced.{% else %}Replace the previous `cockroach` binary or container image with the new binary.{% endif %}
+    1. {% if page.path contains "cockroachcloud" %}The `cockroach` process is restarted and the node rejoins the cluster.{% else %}Restart the `cockroach` process and verify that the node has rejoined the cluster.{% endif %}
 1. When all nodes have rejoined the cluster:
     1. For a patch upgrade within the same major version, the upgrade is complete.
-    1. For a major-version upgrade, the upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). Auto-finalization is enabled by default, and begins as soon as all nodes have rejoined the cluster using the new binary. If you need the ability to [roll back a major-version upgrade](#roll-back-a-major-version-upgrade), you can disable auto-finalization and finalize the upgrade manually. Certain features and performance improvements, such as those that require changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the {% if page.path contains 'cockroachcloud' %} [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}){% else %}[{{ page.version.version }} Release Notes]({% link releases/{{ page.version.version }}.md %}).{% endif %}.
+    1. For a major-version upgrade, the upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). Certain features and performance improvements, such as those requiring changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the {% if page.path contains 'cockroachcloud' %} [Release Notes for the major version]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions){% else %}[{{ page.version.version }} Release Notes]({% link releases/{{ page.version.version }}.md %}){% endif %} for details.
+
+      {% if page.path contains "cockroachcloud" %}In CockroachDB {{ site.data.products.cloud }}, the cluster is finalized automatically after approximately 72 hours. During this time, you can choose to roll back the upgrade or manually finalize the cluster.{% else %}For self-hosted CockroachDB, automatic finalization is enabled by default, and begins as soon as all nodes have rejoined the cluster using the new binary. If you need the ability to [roll back a major-version upgrade](#roll-back-a-major-version-upgrade), you can disable auto-finalization and finalize the upgrade manually.{% endif %}
+
+      Once a major-version upgrade is finalized, the cluster cannot be rolled back to the prior major version.

src/current/_includes/v24.3/upgrade-requirements.md

@@ -3,4 +3,4 @@ CockroachDB v24.3 is a Regular release. To upgrade to it, you must be running ei
 - [v24.2]({% link v24.2/upgrade-cockroach-version.md %}), the previous Innovation release.
 - [v24.1]({% link v24.1/upgrade-cockroach-version.md %}), the previous Regular release.
 
-Before continuing, upgrade to an appropriate version.
+If your cluster is running an earlier version, upgrade to one of these versions before proceeding.