You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2026/10/06 00:29:15 UTC

(pulsar-site) branch main updated (227df02b14e -> 8d2ab105a99)

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git


    from 227df02b14e Pulsar 5.0.0 blog post (#1244)
     new cff00bd5177 Sync release-highlights page with blog post
     new cbd28626e29 Link the 5.0.x upgrade guide from the docs front page and drop etcd and subscription-thread dispatch items from it
     new 8d2ab105a99 Simplify 5.0.x upgrade rollback guidance and group the configuration checklist by priority

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 blog/2026-10-05-announcing-apache-pulsar-5-0.md    |   2 +-
 docs/about.md                                      |   2 +-
 docs/administration-upgrade-to-5.0.x.md            |  40 +++--
 docs/release-highlights.md                         | 178 ++++++++++-----------
 src/css/docs.css                                   |  15 --
 ...cy-percentiles-log-4.0.13-vs-5.0.0-separate.svg |  89 -----------
 .../seek-by-timestamp-offloaded-ranged-reads.svg   | 107 -------------
 versioned_docs/version-5.0.x/about.md              |   2 +-
 .../administration-upgrade-to-5.0.x.md             |  40 +++--
 versioned_docs/version-5.0.x/release-highlights.md | 178 ++++++++++-----------
 10 files changed, 217 insertions(+), 436 deletions(-)
 delete mode 100644 static/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg
 delete mode 100644 static/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg


(pulsar-site) 02/03: Link the 5.0.x upgrade guide from the docs front page and drop etcd and subscription-thread dispatch items from it

Posted by lh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git

commit cbd28626e29a8a0db31e581929e3a2ccbd83f74f
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Mon Oct 5 17:22:25 2026 -0700

    Link the 5.0.x upgrade guide from the docs front page and drop etcd and subscription-thread dispatch items from it
---
 docs/about.md                                                   | 2 +-
 docs/administration-upgrade-to-5.0.x.md                         | 3 +--
 versioned_docs/version-5.0.x/about.md                           | 2 +-
 versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md | 3 +--
 4 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/about.md b/docs/about.md
index 8c6ebaf2855..88a87ab8e58 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -21,7 +21,7 @@ Quick links:
 
 - [Blog: Apache Pulsar 5.0 LTS: Scalable Topics and Faster Existing Workloads](pathname:///blog/2026/10/05/announcing-apache-pulsar-5-0)
 - [Release highlights and upgrading](release-highlights.md)
-- [Cluster upgrade guide](administration-upgrade.md)
+- [Upgrading to Pulsar 5.0.x](administration-upgrade-to-5.0.x.md)
 - [Java client dependency configuration for Pulsar @pulsar:version:major@](pathname:///docs/client-libraries/java-dependency-configuration)
 
 :::
diff --git a/docs/administration-upgrade-to-5.0.x.md b/docs/administration-upgrade-to-5.0.x.md
index 9ffae42a1bc..618fc8059ef 100644
--- a/docs/administration-upgrade-to-5.0.x.md
+++ b/docs/administration-upgrade-to-5.0.x.md
@@ -58,11 +58,10 @@ Use the [configuration default comparison](administration-upgrade-to-5.0.x-confi
 
 - **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
 
-- **etcd is no longer a metadata-store backend.** Migrate deployments using `etcd:` metadata URLs to a supported backend before upgrading. The [ZooKeeper-to-Oxia migration procedure](administration-metadata-store-migration.md) introduced in 5.0 does not migrate etcd. Complete the software upgrade separately from an optional ZooKeeper-to-Oxia migration.
 - **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
 - **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
 - **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
-- **Review dispatch scheduling for expensive entry filters.** `dispatcherDispatchMessagesInSubscriptionThread` changes from `true` to `false`, avoiding an extra subscription-thread handoff. Configurations with compute-heavy server-side broker entry filters may benefit from setting it back to `true`, but this is not a general recommendation: test the change separately with representative workloads. The related `managedLedgerReadEntriesCallbackInline` optimization (default `true`) enables  [...]
+- **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
 - **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
 - **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
 - **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
diff --git a/versioned_docs/version-5.0.x/about.md b/versioned_docs/version-5.0.x/about.md
index 8c6ebaf2855..88a87ab8e58 100644
--- a/versioned_docs/version-5.0.x/about.md
+++ b/versioned_docs/version-5.0.x/about.md
@@ -21,7 +21,7 @@ Quick links:
 
 - [Blog: Apache Pulsar 5.0 LTS: Scalable Topics and Faster Existing Workloads](pathname:///blog/2026/10/05/announcing-apache-pulsar-5-0)
 - [Release highlights and upgrading](release-highlights.md)
-- [Cluster upgrade guide](administration-upgrade.md)
+- [Upgrading to Pulsar 5.0.x](administration-upgrade-to-5.0.x.md)
 - [Java client dependency configuration for Pulsar @pulsar:version:major@](pathname:///docs/client-libraries/java-dependency-configuration)
 
 :::
diff --git a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
index 9ffae42a1bc..618fc8059ef 100644
--- a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
+++ b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
@@ -58,11 +58,10 @@ Use the [configuration default comparison](administration-upgrade-to-5.0.x-confi
 
 - **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
 
-- **etcd is no longer a metadata-store backend.** Migrate deployments using `etcd:` metadata URLs to a supported backend before upgrading. The [ZooKeeper-to-Oxia migration procedure](administration-metadata-store-migration.md) introduced in 5.0 does not migrate etcd. Complete the software upgrade separately from an optional ZooKeeper-to-Oxia migration.
 - **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
 - **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
 - **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
-- **Review dispatch scheduling for expensive entry filters.** `dispatcherDispatchMessagesInSubscriptionThread` changes from `true` to `false`, avoiding an extra subscription-thread handoff. Configurations with compute-heavy server-side broker entry filters may benefit from setting it back to `true`, but this is not a general recommendation: test the change separately with representative workloads. The related `managedLedgerReadEntriesCallbackInline` optimization (default `true`) enables  [...]
+- **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
 - **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
 - **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
 - **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]


(pulsar-site) 03/03: Simplify 5.0.x upgrade rollback guidance and group the configuration checklist by priority

Posted by lh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git

commit 8d2ab105a99e943874b0752ff3c90aa7320178f3
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Mon Oct 5 17:28:28 2026 -0700

    Simplify 5.0.x upgrade rollback guidance and group the configuration checklist by priority
---
 blog/2026-10-05-announcing-apache-pulsar-5-0.md    |  2 +-
 docs/administration-upgrade-to-5.0.x.md            | 37 ++++++++++++++--------
 src/css/docs.css                                   | 13 ++++++++
 .../administration-upgrade-to-5.0.x.md             | 37 ++++++++++++++--------
 4 files changed, 62 insertions(+), 27 deletions(-)

diff --git a/blog/2026-10-05-announcing-apache-pulsar-5-0.md b/blog/2026-10-05-announcing-apache-pulsar-5-0.md
index 72e0e116a3d..a4bc2f06f62 100644
--- a/blog/2026-10-05-announcing-apache-pulsar-5-0.md
+++ b/blog/2026-10-05-announcing-apache-pulsar-5-0.md
@@ -17,7 +17,7 @@ The two are independent: you can upgrade a 4.x cluster to 5.0, keep your current
 Existing partitioned and non-partitioned topics, all subscription types, and the existing Java client, now called the **v4 client**, remain fully supported, and so does ZooKeeper for regular topics. Adopting the v5 client API, Scalable Topics, or Oxia is optional, and none of them is required to benefit from the improvements in 5.0. A typical path looks like this:
 
 1. **Establish your starting point.** Run the latest maintenance release of your 4.0.x or 4.2.x line with your own workloads, and keep that release and its configuration available for rollback.
-2. **Upgrade the cluster.** Prepare for the changes in [Before you upgrade](#before-you-upgrade) and roll out 5.0 while applications keep using the v4 client and existing topics. To keep a path back to your tested 4.x release, set `scalableTopicsEnabled=false` (the default is `true`) on every target broker before the first 5.0 broker starts, and if you use package management for Functions or IO connectors, apply the other [rollback prerequisites](/docs/5.0.x/administration-upgrade-to-5.0 [...]
+2. **Upgrade the cluster.** Prepare for the changes in [Before you upgrade](#before-you-upgrade) and roll out 5.0 while applications keep using the v4 client and existing topics. If you use package management for Functions or IO connectors, apply the [rollback prerequisites](/docs/5.0.x/administration-upgrade-to-5.0.x#preserve-and-rehearse-rollback) before the first 5.0 broker starts.
 3. **Adopt new capabilities when ready.** After validating the cluster and closing the rollback window, adopt the v5 API, Scalable Topics, or Oxia where they help your applications.
 
 ## Scalable Topics: topics that size themselves
diff --git a/docs/administration-upgrade-to-5.0.x.md b/docs/administration-upgrade-to-5.0.x.md
index 618fc8059ef..453fa4b6f7a 100644
--- a/docs/administration-upgrade-to-5.0.x.md
+++ b/docs/administration-upgrade-to-5.0.x.md
@@ -37,8 +37,13 @@ Compare your overrides with [Configuration default changes from 4.x to 5.0](admi
 
 Use **Java 25 with ZGC** for the upgraded servers. Remove existing `PULSAR_GC` overrides from service environment files, container or Helm configuration, and customized `conf/pulsar_env.sh` files so the new release's launcher defaults take effect. Also remove conflicting garbage collector-selection options from `PULSAR_MEM`, `PULSAR_EXTRA_OPTS` or other injected JVM options. Preserve memory sizing in `PULSAR_MEM` rather than carrying forward an old garbage-collector configuration.
 
+<details className="details-plain">
+<summary>ZGC options for Java 21 and Java 25</summary>
+
 Java 25 uses generational ZGC with `-XX:+UseZGC`; it does not need `-XX:+ZGenerational`. When using Java 21, generational ZGC needs to be explicitly enabled with `-XX:+ZGenerational` in addition to `-XX:+UseZGC`. The standard server launcher supplies the appropriate options for either runtime when `PULSAR_GC` is unset. For a custom launcher, verify that its effective JVM options select the appropriate collector for its Java version.
 
+</details>
+
 ### Enable Transparent Huge Pages and configure Linux kernel settings
 
 For high-performance deployments on Linux hosts, set `-Xms` equal to `-Xmx` and add `-XX:+UseTransparentHugePages -XX:+AlwaysPreTouch` in `PULSAR_MEM`. Configure Transparent Huge Pages (THP) in the Linux kernel settings on your hosts, including Kubernetes nodes, before relying on it. See [JVM and Linux host tuning](performance-broker.md#jvm-and-linux-host-tuning) for persistent settings, memory budgeting, and startup considerations.
@@ -56,35 +61,41 @@ Review [Application, Functions, and plugin upgrades](administration-upgrade-to-5
 
 Use the [configuration default comparison](administration-upgrade-to-5.0.x-configuration.md) to review file settings, environment variables, and dynamic overrides.
 
-- **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
+#### Important: act on these before rolling brokers
+
+These changes can stop a component from starting, disable a feature you use, or affect rollback. Apply the ones that match your deployment before the first 5.0 broker starts.
 
+- **Package management for Functions and IO connectors:** package management is disabled by default (`enablePackagesManagement=false`). If you enable it and need rollback to 4.0.x or 4.2.x, set `packagesManagementJsonSerializationEnabled=false` on every target broker before the first 5.0 broker starts, and keep `packagesManagementAllowLegacyJavaSerialization=true` (the default). See [rollback preparation](#preserve-and-rehearse-rollback).
 - **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
 - **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
+- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
+- **Bookie metrics provider:** replace `org.apache.pulsar.metrics.prometheus.bookkeeper.PrometheusMetricsProvider` with `org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider` in `statsProviderClass`. The Pulsar-specific class has been removed. Keep configuration appropriate to each binary during mixed-version rollout; see [BookKeeper configuration](administration-zk-bk.md#pulsar-specific-configuration).
+- **Remove obsolete storage and allocator overrides.** `managedLedgerUnackedRangesOpenCacheSetEnabled` has been removed; individual acknowledgments always use bitmap tracking, while `managedLedgerPersistIndividualAckAsLongArray` still selects the persisted format. Replace the unsupported JVM property `pulsar.allocator.leak_detection` with Netty's `io.netty.leakDetection.level`.
 - **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
+- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
+
+#### Less critical: review and monitor during the canary
+
+These changes adjust defaults or internal behavior. Most deployments need no action, but check them against explicit overrides and watch the related metrics while the first upgraded brokers run.
+
+<details className="details-plain">
+<summary>Defaults and behavior changes to review during the canary</summary>
+
 - **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
 - **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
-- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
-- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
 - **Review the allocator change.** The standard server launcher now defaults to `adaptive` for general Pulsar allocations (`pulsar.allocator.default.type`) and Netty buffers (`io.netty.allocator.type`). To restore the previous pooled behavior, add `-Dpulsar.allocator.default.type=pooled -Dio.netty.allocator.type=pooled` to the existing `PULSAR_EXTRA_OPTS` value and restart the brokers. Keep the separate `ml-cache` allocator adaptive for batch-read cache copies; avoid a global `pulsar.all [...]
 - **Storage reads and acknowledgment persistence:** when `managedLedgerMaxReadsInFlightSizeInMB` is unset, the broker now limits in-flight storage/cache reads to the greater of `dispatcherMaxReadSizeBytes` and 15% of JVM direct memory. An explicit old value of `0` still disables the limit. The defaults for `managedLedgerMaxUnackedRangesToPersist`, `managedLedgerMaxBatchDeletedIndexToPersist`, and `managedLedgerMaxUnackedRangesToPersistInMetadataStore` are now 200,000, and ledger/cursor m [...]
 - **Topic-policy initialization:** `topicPoliciesCacheInitTimeoutSeconds` defaults to 60 seconds. A stuck namespace policy reader is closed and its initialization can be retried, rather than indefinitely blocking topic loading. Test recovery of namespaces with large `__change_events` backlogs and tune the timeout if replay needs longer in your environment.
 - **HTTP executor queues are bounded.** Broker, proxy, and WebSocket HTTP executor queues now enforce `httpServerThreadPoolQueueSize` (default 8192), rather than growing beyond that initial capacity. Rehearse bursts of admin and HTTP traffic and check queue saturation before the rollout.
-- **Remove obsolete storage and allocator overrides.** `managedLedgerUnackedRangesOpenCacheSetEnabled` has been removed; individual acknowledgments always use bitmap tracking, while `managedLedgerPersistIndividualAckAsLongArray` still selects the persisted format. Replace the unsupported JVM property `pulsar.allocator.leak_detection` with Netty's `io.netty.leakDetection.level`.
 - **Review heap sizing:** bucket-based delayed-delivery queues and transaction timeout queues now use heap arrays instead of direct buffers. Compare heap occupancy and GC pauses during the canary; this change does not affect the default in-memory delayed tracker's bitmap index. See [Broker memory](performance-broker.md).
-- **Bookie metrics provider:** replace `org.apache.pulsar.metrics.prometheus.bookkeeper.PrometheusMetricsProvider` with `org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider` in `statsProviderClass`. The Pulsar-specific class has been removed. Keep configuration appropriate to each binary during mixed-version rollout; see [BookKeeper configuration](administration-zk-bk.md#pulsar-specific-configuration).
-- **Package-management service for Functions and IO connectors:** package management is disabled by default (`enablePackagesManagement=false`). If you enable it and need rollback to 4.0.x or 4.2.x, set `packagesManagementJsonSerializationEnabled=false` on every target broker before upgrading, and keep `packagesManagementAllowLegacyJavaSerialization=true` (the default). See [rollback preparation](#preserve-and-rehearse-rollback).
+
+</details>
 
 ### Preserve and rehearse rollback
 
 Rollback is intended for workloads that retain the pre-upgrade feature set and formats readable by the previous version. For a 4.0.x deployment, this means preserving the existing 4.0.x feature set; using that feature set alone is not sufficient if package or shared metadata has been rewritten incompatibly. Use the exact pre-upgrade release as the rollback target, rather than assuming that any 4.x version is interchangeable. Keep the previous binaries or images, configuration, connector  [...]
 
-To preserve this rollback path, disable scalable-topic services in the configuration of **every target 5.0 broker before the first one starts**:
-
-```properties
-scalableTopicsEnabled=false
-```
-
-Changing this setting requires a broker restart. It disables scalable-topic services, scalable-topic admin APIs and client access, and segment loading. The v5 API also requires these services for regular topics, so continue using the v4 API while this setting is disabled. This applies even if the application uses the combined `pulsar-client-v5-all` or `pulsar-client-v5-shaded` dependency; v4 API usage does not require scalable-topic services. Existing scalable-topic data is retained but  [...]
+Scalable topics can stay enabled during the upgrade. If you roll back to 4.x, the data and metadata of scalable topics created on 5.0 remain persisted, and after you upgrade to 5.0 again, those topics can be used again. The 4.x brokers serve the existing partitioned and non-partitioned topics as before. Converting an existing regular topic to a scalable topic is one-way, so plan [topic migration](admin-api-scalable-topics.md#migrate-a-regular-topic) after the rollback window has closed.  [...]
 
 Package management is **disabled by default** (`enablePackagesManagement=false`). If you enable it to store Pulsar Functions or IO connector packages (`function://`, `source://`, or `sink://` URLs), preserve the Java metadata format while rollback to 4.0.x or 4.2.x is required. Configure every target broker before the first upgraded broker starts:
 
diff --git a/src/css/docs.css b/src/css/docs.css
index 69e6b0e362e..580ba173d4c 100644
--- a/src/css/docs.css
+++ b/src/css/docs.css
@@ -20,6 +20,19 @@
   margin-top: 0.5rem;
 }
 
+/* Plain collapsible: drop the info-alert colors that Docusaurus adds to every <details>. */
+.details-plain.alert {
+  --ifm-alert-background-color: transparent;
+  --ifm-alert-background-color-highlight: var(--ifm-color-emphasis-100);
+  --ifm-alert-foreground-color: var(--ifm-font-color-base);
+  --ifm-alert-border-color: var(--ifm-color-emphasis-300);
+  --ifm-alert-border-left-width: var(--ifm-alert-border-width);
+  --ifm-link-color: var(--ifm-color-primary);
+  --ifm-link-hover-color: var(--ifm-color-primary-dark);
+  --ifm-link-decoration: none;
+  --docusaurus-details-decoration-color: var(--ifm-color-emphasis-600);
+}
+
 /* Use same blue color for NOTE admonition as for INFO */
 [class*="docs-doc-page"] .alert--secondary {
   --ifm-alert-background-color: var( --ifm-color-info-contrast-background );
diff --git a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
index 618fc8059ef..453fa4b6f7a 100644
--- a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
+++ b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
@@ -37,8 +37,13 @@ Compare your overrides with [Configuration default changes from 4.x to 5.0](admi
 
 Use **Java 25 with ZGC** for the upgraded servers. Remove existing `PULSAR_GC` overrides from service environment files, container or Helm configuration, and customized `conf/pulsar_env.sh` files so the new release's launcher defaults take effect. Also remove conflicting garbage collector-selection options from `PULSAR_MEM`, `PULSAR_EXTRA_OPTS` or other injected JVM options. Preserve memory sizing in `PULSAR_MEM` rather than carrying forward an old garbage-collector configuration.
 
+<details className="details-plain">
+<summary>ZGC options for Java 21 and Java 25</summary>
+
 Java 25 uses generational ZGC with `-XX:+UseZGC`; it does not need `-XX:+ZGenerational`. When using Java 21, generational ZGC needs to be explicitly enabled with `-XX:+ZGenerational` in addition to `-XX:+UseZGC`. The standard server launcher supplies the appropriate options for either runtime when `PULSAR_GC` is unset. For a custom launcher, verify that its effective JVM options select the appropriate collector for its Java version.
 
+</details>
+
 ### Enable Transparent Huge Pages and configure Linux kernel settings
 
 For high-performance deployments on Linux hosts, set `-Xms` equal to `-Xmx` and add `-XX:+UseTransparentHugePages -XX:+AlwaysPreTouch` in `PULSAR_MEM`. Configure Transparent Huge Pages (THP) in the Linux kernel settings on your hosts, including Kubernetes nodes, before relying on it. See [JVM and Linux host tuning](performance-broker.md#jvm-and-linux-host-tuning) for persistent settings, memory budgeting, and startup considerations.
@@ -56,35 +61,41 @@ Review [Application, Functions, and plugin upgrades](administration-upgrade-to-5
 
 Use the [configuration default comparison](administration-upgrade-to-5.0.x-configuration.md) to review file settings, environment variables, and dynamic overrides.
 
-- **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
+#### Important: act on these before rolling brokers
+
+These changes can stop a component from starting, disable a feature you use, or affect rollback. Apply the ones that match your deployment before the first 5.0 broker starts.
 
+- **Package management for Functions and IO connectors:** package management is disabled by default (`enablePackagesManagement=false`). If you enable it and need rollback to 4.0.x or 4.2.x, set `packagesManagementJsonSerializationEnabled=false` on every target broker before the first 5.0 broker starts, and keep `packagesManagementAllowLegacyJavaSerialization=true` (the default). See [rollback preparation](#preserve-and-rehearse-rollback).
 - **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
 - **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
+- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
+- **Bookie metrics provider:** replace `org.apache.pulsar.metrics.prometheus.bookkeeper.PrometheusMetricsProvider` with `org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider` in `statsProviderClass`. The Pulsar-specific class has been removed. Keep configuration appropriate to each binary during mixed-version rollout; see [BookKeeper configuration](administration-zk-bk.md#pulsar-specific-configuration).
+- **Remove obsolete storage and allocator overrides.** `managedLedgerUnackedRangesOpenCacheSetEnabled` has been removed; individual acknowledgments always use bitmap tracking, while `managedLedgerPersistIndividualAckAsLongArray` still selects the persisted format. Replace the unsupported JVM property `pulsar.allocator.leak_detection` with Netty's `io.netty.leakDetection.level`.
 - **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
+- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
+
+#### Less critical: review and monitor during the canary
+
+These changes adjust defaults or internal behavior. Most deployments need no action, but check them against explicit overrides and watch the related metrics while the first upgraded brokers run.
+
+<details className="details-plain">
+<summary>Defaults and behavior changes to review during the canary</summary>
+
 - **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
 - **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
-- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
-- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
 - **Review the allocator change.** The standard server launcher now defaults to `adaptive` for general Pulsar allocations (`pulsar.allocator.default.type`) and Netty buffers (`io.netty.allocator.type`). To restore the previous pooled behavior, add `-Dpulsar.allocator.default.type=pooled -Dio.netty.allocator.type=pooled` to the existing `PULSAR_EXTRA_OPTS` value and restart the brokers. Keep the separate `ml-cache` allocator adaptive for batch-read cache copies; avoid a global `pulsar.all [...]
 - **Storage reads and acknowledgment persistence:** when `managedLedgerMaxReadsInFlightSizeInMB` is unset, the broker now limits in-flight storage/cache reads to the greater of `dispatcherMaxReadSizeBytes` and 15% of JVM direct memory. An explicit old value of `0` still disables the limit. The defaults for `managedLedgerMaxUnackedRangesToPersist`, `managedLedgerMaxBatchDeletedIndexToPersist`, and `managedLedgerMaxUnackedRangesToPersistInMetadataStore` are now 200,000, and ledger/cursor m [...]
 - **Topic-policy initialization:** `topicPoliciesCacheInitTimeoutSeconds` defaults to 60 seconds. A stuck namespace policy reader is closed and its initialization can be retried, rather than indefinitely blocking topic loading. Test recovery of namespaces with large `__change_events` backlogs and tune the timeout if replay needs longer in your environment.
 - **HTTP executor queues are bounded.** Broker, proxy, and WebSocket HTTP executor queues now enforce `httpServerThreadPoolQueueSize` (default 8192), rather than growing beyond that initial capacity. Rehearse bursts of admin and HTTP traffic and check queue saturation before the rollout.
-- **Remove obsolete storage and allocator overrides.** `managedLedgerUnackedRangesOpenCacheSetEnabled` has been removed; individual acknowledgments always use bitmap tracking, while `managedLedgerPersistIndividualAckAsLongArray` still selects the persisted format. Replace the unsupported JVM property `pulsar.allocator.leak_detection` with Netty's `io.netty.leakDetection.level`.
 - **Review heap sizing:** bucket-based delayed-delivery queues and transaction timeout queues now use heap arrays instead of direct buffers. Compare heap occupancy and GC pauses during the canary; this change does not affect the default in-memory delayed tracker's bitmap index. See [Broker memory](performance-broker.md).
-- **Bookie metrics provider:** replace `org.apache.pulsar.metrics.prometheus.bookkeeper.PrometheusMetricsProvider` with `org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider` in `statsProviderClass`. The Pulsar-specific class has been removed. Keep configuration appropriate to each binary during mixed-version rollout; see [BookKeeper configuration](administration-zk-bk.md#pulsar-specific-configuration).
-- **Package-management service for Functions and IO connectors:** package management is disabled by default (`enablePackagesManagement=false`). If you enable it and need rollback to 4.0.x or 4.2.x, set `packagesManagementJsonSerializationEnabled=false` on every target broker before upgrading, and keep `packagesManagementAllowLegacyJavaSerialization=true` (the default). See [rollback preparation](#preserve-and-rehearse-rollback).
+
+</details>
 
 ### Preserve and rehearse rollback
 
 Rollback is intended for workloads that retain the pre-upgrade feature set and formats readable by the previous version. For a 4.0.x deployment, this means preserving the existing 4.0.x feature set; using that feature set alone is not sufficient if package or shared metadata has been rewritten incompatibly. Use the exact pre-upgrade release as the rollback target, rather than assuming that any 4.x version is interchangeable. Keep the previous binaries or images, configuration, connector  [...]
 
-To preserve this rollback path, disable scalable-topic services in the configuration of **every target 5.0 broker before the first one starts**:
-
-```properties
-scalableTopicsEnabled=false
-```
-
-Changing this setting requires a broker restart. It disables scalable-topic services, scalable-topic admin APIs and client access, and segment loading. The v5 API also requires these services for regular topics, so continue using the v4 API while this setting is disabled. This applies even if the application uses the combined `pulsar-client-v5-all` or `pulsar-client-v5-shaded` dependency; v4 API usage does not require scalable-topic services. Existing scalable-topic data is retained but  [...]
+Scalable topics can stay enabled during the upgrade. If you roll back to 4.x, the data and metadata of scalable topics created on 5.0 remain persisted, and after you upgrade to 5.0 again, those topics can be used again. The 4.x brokers serve the existing partitioned and non-partitioned topics as before. Converting an existing regular topic to a scalable topic is one-way, so plan [topic migration](admin-api-scalable-topics.md#migrate-a-regular-topic) after the rollback window has closed.  [...]
 
 Package management is **disabled by default** (`enablePackagesManagement=false`). If you enable it to store Pulsar Functions or IO connector packages (`function://`, `source://`, or `sink://` URLs), preserve the Java metadata format while rollback to 4.0.x or 4.2.x is required. Configure every target broker before the first upgraded broker starts:
 


(pulsar-site) 01/03: Sync release-highlights page with blog post

Posted by lh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git

commit cff00bd5177cf8c3dc9b30536c6e03187ed7741b
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Mon Oct 5 17:11:20 2026 -0700

    Sync release-highlights page with blog post
---
 docs/release-highlights.md                         | 178 ++++++++++-----------
 src/css/docs.css                                   |  28 ----
 ...cy-percentiles-log-4.0.13-vs-5.0.0-separate.svg |  89 -----------
 .../seek-by-timestamp-offloaded-ranged-reads.svg   | 107 -------------
 versioned_docs/version-5.0.x/release-highlights.md | 178 ++++++++++-----------
 5 files changed, 164 insertions(+), 416 deletions(-)

diff --git a/docs/release-highlights.md b/docs/release-highlights.md
index 10237f30a51..a6f97d143fe 100644
--- a/docs/release-highlights.md
+++ b/docs/release-highlights.md
@@ -9,14 +9,14 @@ import ReleaseSeriesNotes from '@site/src/components/ReleaseSeriesNotes';
 
 Pulsar 5.0 introduces **Scalable Topics** for applications that need to grow beyond a fixed partition count, alongside **major performance and reliability improvements for existing workloads**. Scale topics and consumers as demand changes, benefit from more efficient brokers, and keep the applications and topics you already run.
 
-- **Scalable Topics: grow beyond a fixed partition count.** Traditional partitions cannot shrink, and adding partitions can disrupt per-key ordering. Sizing too generously wastes resources; sizing too narrowly creates hot partitions and costly migrations. Scalable Topics let you split and merge key ranges and scale consumers while preserving per-key ordering and producer batching.
-- **More performance from existing workloads.** Fewer thread handoffs, less contention, and batched storage reads reduce the work behind each message. In one [many-publisher benchmark](#keep-consumers-at-the-tail-with-many-publishers), backlog growth during publishing fell from **128,585 to 173 messages/s (−99.9%)**, and the maximum backlog fell by **99.7%**. In this workload, consumers stayed at the tail with hundreds of publishers without accumulating a sustained backlog.
+- **Scalable Topics: topics that size themselves.** Instead of choosing a partition count up front, a scalable topic splits hot key-range segments and merges cold ones at runtime, while preserving per-key ordering and producer batching.
+- **More performance from existing workloads.** Fewer thread handoffs, less contention, and batched storage reads reduce the work behind each message. In a [benchmark with 500 publishers](#keep-consumers-at-the-tail-with-many-publishers), consumers stayed at the tail instead of stalling behind the producers, the broker sustained about **1.7× the total load**, published plus consumed, and p99 end-to-end latency fell from **202.3 s to 1.08 s**.
 - **More dependable delivery.** Fixes across geo-replication, subscriptions, delayed delivery, and acknowledgment recovery address stalls in the features applications use every day.
 - **Easier operation at scale.** Better load distribution, coordinated rolling-upgrade guidance, structured logs, and the ability to close idle topics without deleting their data give operators more control.
 
 :::tip Upgrade with confidence
 
-**Keep your applications and topics.** Existing partitioned and non-partitioned topics, subscription types, and the existing Java client—now called the **v4 client**—remain supported. Your v4 applications can keep their client dependency and API when you upgrade the cluster. With Scalable Topics disabled, all previously available features remain fully supported in production on ZooKeeper.
+**Keep your applications and topics.** Existing partitioned and non-partitioned topics, subscription types, and the existing Java client—now called the **v4 client**—remain supported. Your v4 applications can keep their client dependency and API when you upgrade the cluster. ZooKeeper remains fully supported as the metadata store.
 
 **Adopt new capabilities on your schedule.** The v5 client API, Scalable Topics, and Oxia are separate choices. Upgrade your cluster first, then introduce the capabilities that suit your applications.
 
@@ -32,126 +32,110 @@ Pulsar 5.0 introduces **Scalable Topics** for applications that need to grow bey
 
 <!-- Release-note links update automatically. Retain this page's stable document ID. -->
 
-## Scalable Topics {#scalable-topics}
+## Scalable Topics: topics that size themselves {#scalable-topics}
 
-[Scalable Topics](concepts-scalable-topics.md) give applications a logical topic that can grow as demand changes. Key-range segments can split and merge, so applications use a `topic://` address without managing a partition count.
+A topic should be a **logical concept**: a named stream that applications publish to and consume from. Yet for its whole history, Pulsar has asked application developers to answer an infrastructure question up front: **how many partitions?** That number is a guess that is easy to get wrong and hard to undo. It is chosen before you know the real traffic, it can be increased but never decreased, and because keys are routed with `hash(key) % partitionCount`, increasing it moves keys to diff [...]
 
-Consumer parallelism can grow within each segment, too. Multiple consumers share the work while preserving per-key ordering, including when consumers join or leave. This helps drain backlogs left in segments after they split or merge and lets applications keep producer batching enabled without selecting a key-based batcher for this consumption mode.
+**[Scalable Topics](concepts-scalable-topics.md) take that decision away.** A scalable topic, addressed with the new `topic://` scheme, is a single logical stream whose capacity follows its actual load, in both directions:
 
-Existing persistent topics can be [migrated in place](admin-api-scalable-topics.md#migrate-a-regular-topic), without copying their data, after their producers and consumers move to the v5 client. [Transactions](txn-use.md#transactions-on-scalable-topics) work across segment splits and merges when enabled on brokers using Oxia. In production, Scalable Topics use Oxia; ZooKeeper deployments can try them in test environments. The [administration guide](admin-api-scalable-topics.md) covers s [...]
+- **Key-range segments.** The key hash space is divided into segments, each owning a contiguous range and backed by its own internal topic.
+- **Split and merge at runtime.** The broker splits hot segments and merges adjacent cold ones with no downtime. This is automatic by default, with thresholds you can tune per broker, namespace, and topic, and you can also split and merge manually.
+- **Per-key ordering is preserved.** A split or merge moves a key to a successor range that still contains it, and stream consumers drain the predecessor segment before reading its successor.
+- **Applications see one stream.** A per-topic controller in the broker manages the segment layout and pushes changes to clients, so applications never handle segments or react to resizing.
 
-Operators can keep Scalable Topics behind a feature gate during the upgrade by setting `scalableTopicsEnabled=false` on every target broker before the first 5.0 broker starts. Together with the other [rollback prerequisites](administration-upgrade-to-5.0.x.md#preserve-and-rehearse-rollback), this preserves a safe path back to the tested 4.x release if problems arise during the 5.x upgrade. Enable the feature in production when you are ready, after validating the upgraded cluster and clos [...]
+Consumer parallelism can grow within a segment, too. Messages are grouped into **entry buckets** by key hash, and multiple stream consumers share a segment's buckets in key order, including when consumers join or leave. When more consumers join, Pulsar can split a busy segment or give it more buckets, and after a split or merge, consumers share the sealed segment's buckets to drain its backlog. **If you have struggled to combine Key_Shared subscriptions with producer batching, this addre [...]
 
-## Performance and reliability {#performance-and-reliability}
+| | Partitioned topic (v4) | Scalable topic |
+| --- | --- | --- |
+| Capacity | Partition count chosen at creation | Segments and entry buckets that change at runtime |
+| Scale up | Increase the partition count manually | Hot segments split automatically |
+| Scale down | Not possible | Cold segments merge automatically |
+| Key ordering when resized | Keys can move between partitions | Preserved across splits and merges for stream consumers |
+| Layout visible to applications | Partition count and indexes | None; managed by the broker |
 
-:::tip
-
-The performance and reliability improvements in Pulsar 5.0 apply to existing applications and topics. They don't require adopting Scalable Topics or the v5 client API. After [upgrading from Pulsar 4.x](administration-upgrade-to-5.0.x.md), existing applications continue to work with all their current features and benefit from these improvements without code changes.
-
-:::
-
-### Keep consumers at the tail with 100s of publishers {#keep-consumers-at-the-tail-with-many-publishers}
+The goal is for one topic type to be the right choice across use cases, out of the box: you model your application around the topics that fit your domain, and Pulsar adapts them to how they are actually used, without capacity planning or re-sharding.
 
-In a typical IoT deployment, hundreds of thousands of devices connect to hundreds of gateways, and each gateway publishes the devices' telemetry to Pulsar, which serves as the message bus for the applications that process it. The messages are keyed by device ID, so that each device's messages are processed in order, and for that reason they usually aren't batched. Pulsar 5.0 reduces the broker queueing and contention that could make the consuming applications fall behind even when they w [...]
+Scalable Topics are delivered by a family of Pulsar Improvement Proposals:
 
-A benchmark compared Pulsar 4.0.13 and 5.0.0 in a simplified version of this use case:
+- **[PIP-460](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-460.md)**: Scalable Topics, the overall model
+- **[PIP-468](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-468.md)**: the per-topic controller
+- **[PIP-483](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-483.md)**: automatic split and merge
+- **[PIP-486](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-486.md)**: key-shared consumption with entry buckets
+- **[PIP-466](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-466.md)**: the v5 Java client API
+- **[PIP-473](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-473.md)**: transactions across splits and merges
+- **[PIP-475](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-475.md)**: in-place migration of regular topics, with no data copy
+- **[PIP-494](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-494.md)**: the client specification and its change process
+- **[PIP-496](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-496.md)**: Functions and IO connectors on Scalable Topics
 
-- **500 gateways** publish keyed, unbatched 128-byte messages to one shared topic, as fast as the cluster accepts them.
-- **20 instances of a message-processing application** consume them from that topic on one Key_Shared subscription, which delivers each key's messages in order to one instance at a time.
-- Each gateway and each application instance has its own Pulsar client and TCP connection.
+### A client specification for every SDK {#scalable-topics-client-specification}
 
-The results:
+With Scalable Topics, clients do more than connect to a topic: they track the segment layout as it changes, route each key to the segment that owns it, and follow the controller's consumer assignments. To make every client behave the same way, Pulsar 5.0 ships the **[Scalable Topics Client Specification](https://github.com/apache/pulsar/tree/v5.0.0/spec/scalable-topics) 1.0**, the authoritative, language-neutral contract for Scalable Topics clients:
 
-<div className="release-highlights-benchmark">
+- **One contract for all languages.** It separates the API contract that applications observe from a client's internal mechanisms and the exact wire-protocol interactions, documented with sequence diagrams. Conformant clients route keys identically and share ordering and acknowledgment semantics, so producers and consumers written in different languages can work on the same scalable topic.
+- **Stable and versioned.** Each feature has a stability tier. Incompatible changes land only at an LTS boundary, deprecated features remain available at least until the next LTS release, and every normative change goes through a PIP together with its specification edits.
+- **A clear definition of support.** A conformance checklist defines what an SDK must implement to claim Scalable Topics support. The Java v5 client is the reference implementation, while the specification is the source of truth.
 
-| Means of 3 runs | 4.0.13 | 5.0.0 | Change |
-| --- | ---: | ---: | ---: |
-| Publishing rate, messages/s | 128,716 | 107,048 | −16.8% |
-| Consuming rate during publishing, messages/s | 131 | 106,875 | ×816 |
-| **Backlog growth rate during publishing, messages/s** | **128,585** | **173** | **−99.9%** |
-| Delivered throughput, until the last message arrived, messages/s | 17,038 | 106,658 | +526% |
-| Time the consumers needed after publishing ended | 202–205 s | 0 s | |
-| **Maximum backlog, messages** | **3,990,044** | **12,729** | **−99.7%** |
-| End-to-end latency, p99 | 202.3 s | 1.08 s | −99.5% |
+Today, the Java [v5 client](#v5-java-client) supports Scalable Topics, and work is ongoing to bring that support to the other Pulsar client SDKs.
 
-</div>
+### Adopting Scalable Topics {#adopting-scalable-topics}
 
-**Backlog growth rate during publishing** is **publishing rate − consumption rate during publishing**, or equivalently **(messages published − messages consumed by the time all publishers finished) ÷ publishing duration in seconds**. A lower value means consumers keep closer to the publishers.
+- **New applications** are encouraged to build on Scalable Topics and the v5 API when the [requirements and limitations](concepts-scalable-topics.md#requirements) fit.
+- **Existing applications** can keep their partitioned and non-partitioned topics, with no requirement to migrate. When you're ready, existing persistent topics can be [migrated in place](admin-api-scalable-topics.md#migrate-a-regular-topic), without copying their data, once their producers and consumers use the v5 client. The conversion is one-way.
+- **Requirements:** a client with v5 API support, since v4 clients cannot use `topic://` topics, and scalable-topic services enabled on the brokers, which the v5 API needs even for regular topics. Scalable Topics work with ZooKeeper and Oxia, with Oxia recommended, and support [transactions](txn-use.md#transactions-on-scalable-topics) across segment splits and merges.
+- **Functions and IO connectors:** Java Functions and IO connectors switch to the v5 client automatically when their topics are `topic://` topics. Python and Go Functions keep the v4 client and cannot use `topic://` topics.
+- **Limitations:** geo-replication and replicated subscriptions are not supported for Scalable Topics in 5.0. Use partitioned or non-partitioned topics for applications that need them.
 
-**Delivered throughput** is calculated for each run as **4,000,000 messages ÷ elapsed seconds from the start of publishing until the last message was consumed**, including any time spent draining the backlog after publishing ended. The table reports the mean of the three runs.
+Operators can keep Scalable Topics behind a feature gate during the upgrade by setting `scalableTopicsEnabled=false` (the default is `true`) on every target broker before the first 5.0 broker starts. Together with the other [rollback prerequisites](administration-upgrade-to-5.0.x.md#preserve-and-rehearse-rollback), this preserves a safe path back to the tested 4.x release if problems arise during the 5.x upgrade. Enable the feature in production when you are ready, after validating the u [...]
 
-What the results show:
+The v4 API and existing topic types remain fully supported throughout the 5.0 LTS line. Longer term, Scalable Topics are designed to cover all of Pulsar's use cases, and the v5 API is the direction Pulsar is heading; according to [PIP-460](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-460.md), any deprecation of the existing API would be planned for a later LTS release.
 
-- **4.0.13's consumers fell behind:** they received almost nothing while the producers published, and needed more than 200 s afterwards to catch up.
-- **5.0.0's consumers kept up:** they received the messages as fast as they were published, about 1 s after publishing at p99.
-- **4.0.13 published faster** because its broker was hardly delivering anything at the same time, while 5.0.0's broker did both.
+To get started, read the [Scalable Topics concepts](concepts-scalable-topics.md), the [v5 Java client guide](pathname:///docs/client-libraries/java-v5), and [Manage scalable topics](admin-api-scalable-topics.md).
 
-Throughput of one run of each version, each in a panel of its own with the same axes. With 4.0.13, consumption (the solid line) stays near zero until publishing ends, then drains the backlog at about 20,000 messages/s for more than 200 s; with 5.0.0, it follows publishing (the dashed line):
-
-![Throughput of Pulsar 4.0.13 and 5.0.0: published and consumed messages per second, in separate panels with the same axes](/assets/release-highlights-5.0/throughput-4.0.13-vs-5.0.0-separate.svg)
-
-Publish and end-to-end latency by percentile, on a logarithmic scale. The publish latencies are similar, about 1 s, while 4.0.13's end-to-end latency reaches about 200 s:
-
-![Latency by percentile of Pulsar 4.0.13 and 5.0.0 on a logarithmic scale, in separate panels with the same axes](/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg)
-
-For these **tailing reads**—consuming newly published messages near the end of the topic—fewer thread handoffs and batched publish submission let dispatch keep moving instead of waiting behind one executor task per entry.
-
-How it was measured:
+## Performance and reliability for existing workloads {#performance-and-reliability}
 
-- [Pulsar's performance testing framework](https://github.com/apache/pulsar/tree/master/tests/performance) ran its [`iot-telemetry-max-rate`](https://github.com/apache/pulsar/blob/master/tests/performance/scenarios/iot-telemetry-max-rate.yaml) scenario, with single-copy ledgers on three bookies, on one 8-core host at a fixed 2.4 GHz.
-- Each run measured 4 million messages after a warmup. With 4.0.13, publishing took about 31 s and the last message arrived after about 235 s; with 5.0.0, both took about 37 s.
-- The topic was a regular persistent topic, not a Scalable Topic, so that both versions ran the same kind of topic and the comparison with 4.0.13 is like for like.
-- 4.0.13 ran with its own defaults, and both versions used the same 5.0.0 client. Every run delivered every message without duplicates or ordering violations.
-
-The results describe this workload, not general broker capacity: run the scenario on your own hardware to compare with your application. Consumers still need enough processing capacity to keep up with producers.
-
-### Seek by timestamp in offloaded topics with fewer object store requests {#seek-by-timestamp-in-offloaded-topics}
-
-Topics with long retention, for example 1 year, hold most of their history in [tiered storage](tiered-storage-overview.md). Seeking such a topic to a timestamp runs a binary search over its offloaded ledgers, but their index records only the first entry of each data block, so reaching any other entry meant scanning the block from its start, one ranged read at a time. Pulsar 5.0 remembers the entry offsets it finds and makes use of the indexed block starts, so a search sends about **90% f [...]
+:::tip
 
-<div className="release-highlights-benchmark">
+The performance and reliability improvements in Pulsar 5.0 apply to existing applications and topics. They don't require adopting Scalable Topics or the v5 client API. After [upgrading from Pulsar 4.x](administration-upgrade-to-5.0.x.md), existing applications continue to work with all their current features and benefit from these improvements without code changes.
 
-| Ranged reads per search, 1 MiB each | Before | 5.0.0 | Change |
-| --- | ---: | ---: | ---: |
-| **Cold search, mean of 16 searches** | **428** | **44** | **−90%** |
-| Warm search, mean of 16 searches | 223 | 9 | −96% |
-| Cold search, maximum | 738 | 70 | −91% |
+:::
 
-</div>
+### Consumers keep up with hundreds of publishers {#keep-consumers-at-the-tail-with-many-publishers}
 
-A **cold search** runs with no entry offset cached; a **warm search** follows it and seeks 200 entries earlier, as when a consumer seeks again nearby. **Before** is Pulsar 4.0.13 and 4.2.4.
+In a typical IoT deployment, devices connect to hundreds of gateways that publish the devices' telemetry to Pulsar. Messages are keyed by device ID so that each device's messages are processed in order, and for that reason they are often not batched.
 
-![Ranged reads sent to the object store per search by timestamp on offloaded ledgers, before the changes and after each of the three changes, for cold and warm searches in separate panels with the same axis](/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg)
+A benchmark compared Pulsar 4.0.13 and 5.0.0 on a simplified version of this use case: **500 publishers** sent keyed, unbatched 128-byte messages, as fast as the broker accepted them, to one regular persistent topic, consumed by **20 consumers** on one Key_Shared subscription. Each publisher and consumer had its own client and connection, and both versions were driven by the same 5.0.0 Java client. The table shows the means of three runs.
 
-The figures count requests and bytes, not latency, which depends on your object store. See [read performance for object storage](tiered-storage-overview.md#read-performance-for-object-storage) for the settings involved, and the [message position search metrics](reference-metrics-opentelemetry.md#message-position-search-metrics) to observe searches on a running broker.
+| | 4.0.13 | 5.0.0 |
+| --- | ---: | ---: |
+| Publishing rate, messages/s | 128,716 | 107,048 |
+| Consuming rate during publishing, messages/s | 131 | 106,875 |
+| Published + consumed, messages/s | 128,847 | 213,923 |
+| End-to-end latency, p99 | 202.3 s | 1.08 s |
 
-<details className="details-plain">
-<summary>Offloaded-ledger seek improvements in detail and how they were measured</summary>
+Once the broker reached its CPU limit, contention between threads in 4.0.13 left the consumers stalled behind the producers: they received almost nothing until publishing ended, and the backlog grew to almost 4 million messages. 4.0.13 accepted messages faster only because it was barely delivering any. Pulsar 5.0.0 shares the broker fairly between publishing and dispatch, so consumers stay at the tail and it sustains about **1.7× the total load**, published plus consumed.
 
-What each change contributes:
+![Throughput of one run of Pulsar 4.0.13 and of 5.0.0: published and consumed messages per second, in separate panels with the same axes](/assets/release-highlights-5.0/throughput-4.0.13-vs-5.0.0-separate.svg)
 
-- **Entry offsets found while scanning are reused:** a scan caches the offset of every entry it passes, and a later read starts from a nearby cached offset instead of the start of the block. Cold searches go from 428 to 156 ranged reads, and warm searches from 223 to 14.
-- **The search reads the first entry of data blocks:** when the first entry of a data block is close to the midpoint of the search range, the search reads that entry instead, with a single ranged read. Cold searches go from 156 to 61, and warm searches from 14 to 9.
-- **Offsets are remembered for each open ledger:** scans keep offsets about 1 MiB apart for as long as the offloaded ledger stays open, and later reads in the same data block resume from the nearest one. Cold searches go from 61 to 44, and warm searches stay at 9.
+The gains come mainly from fewer thread handoffs and batched publish submission, which keep dispatch moving instead of waiting behind one executor task per entry. These results describe this workload, not general broker capacity. Consumers still need enough processing capacity to keep up with producers.
 
 How it was measured:
 
-- The topic held about 130,000 entries of 2 to 6 KiB in two offloaded ledgers of about 250 MiB each, with 64 MiB data blocks and a 1 MiB read buffer.
-- [`OffloadedLedgerFindPositionTest`](https://github.com/apache/pulsar/blob/master/tiered-storage/jcloud/src/test/java/org/apache/bookkeeper/mledger/offload/jcloud/impl/OffloadedLedgerFindPositionTest.java) ran before the first change and after each change, with its data set to this layout. As committed, the test uses 16 MiB data blocks and one ledger to stay small.
-- The object store was in memory, and the broker entry cache was disabled so that every entry read reached the offloaded ledger.
-- The 16 searched positions are spread over both ledgers and over the positions within their data blocks. Each search covers both ledgers; a seek first narrows the search to the ledgers that can contain the timestamp.
-
-</details>
+- [Pulsar's performance testing framework](https://github.com/apache/pulsar/tree/v5.0.0/tests/performance) ran its [`iot-telemetry-max-rate`](https://github.com/apache/pulsar/blob/v5.0.0/tests/performance/scenarios/iot-telemetry-max-rate.yaml) scenario, with single-copy ledgers on three bookies, on one 8-core host at a fixed 2.4 GHz. You can run the scenario on your own hardware to compare with your application.
+- Each run measured 4 million messages after a warmup. With 4.0.13, publishing took about 31 s and the last message arrived after about 235 s; with 5.0.0, both took about 37 s.
+- The topic was a regular persistent topic, not a Scalable Topic, so that both versions ran the same kind of topic and the comparison with 4.0.13 is like for like. 4.0.13 ran with its own defaults. Every run delivered every message without duplicates or ordering violations.
+- **Consuming rate during publishing** counts the messages consumed by the time all publishers finished, divided by the publishing duration. **Published + consumed** is the sum of the publishing rate and the consuming rate during publishing, the total message load the broker handled while publishing.
 
 ### Less work per message {#less-work-per-message}
 
-The efficiency improvements reach across the messaging path:
+- **Publishing and dispatch:** batched handovers reduce executor contention, producers on a topic with deduplication enabled no longer contend on a topic-wide lock, and Shared and Key_Shared dispatch use fewer synchronization and lookup operations.
+- **Storage and memory:** [BookKeeper batch reads](https://bookkeeper.apache.org/bps/BP-62-new-API-for-batched-reads/) fetch multiple entries per request when draining backlogs of small entries, cache-owned copies and Netty's adaptive allocator improve buffer use, and deferred metadata parsing reduces work when publishing.
+- **Acknowledgments and client scheduling:** compact bitmaps, reused acknowledgment data, and coalesced listener notifications reduce allocation and scheduling overhead; the client-side changes take effect with the 5.0 client library.
 
-- **Publishing and dispatch:** batched handovers reduce executor contention, independent producers avoid a topic-wide deduplication lock, and Shared and Key_Shared dispatch use fewer synchronization and lookup operations.
-- **Storage and memory:** BookKeeper batch reads fetch multiple entries per request using [BP-62 New API for batched reads](https://bookkeeper.apache.org/bps/BP-62-new-API-for-batched-reads/). Cache-owned copies and the [Netty adaptive allocator](https://netty.io/wiki/analyzing-memory-allocator-behavior.html) improve buffer use for small entries. Deferred metadata parsing reduces work on the publishing path, and tiered-storage reads reuse discovered entry offsets.
-- **Acknowledgments and client scheduling:** compact bitmaps, reused acknowledgment data, fewer temporary objects, and coalesced listener notifications reduce allocation and scheduling overhead.
+The [broker performance guide](performance-broker.md) covers the related settings and how to tune them. The [configuration comparison](administration-upgrade-to-5.0.x-configuration.md) helps operators review changed defaults against their own workloads.
 
-The [broker performance guide](performance-broker.md) explains the improvements and tuning options. The [configuration comparison](administration-upgrade-to-5.0.x-configuration.md) helps operators review changed defaults against their own workloads.
+### Seek by timestamp on offloaded topics with fewer object-store requests {#seek-by-timestamp-in-offloaded-topics}
+
+Seeking a topic in [tiered storage](tiered-storage-overview.md) to a timestamp previously meant scanning offloaded data blocks from their start, one ranged read at a time. Pulsar 5.0 remembers the entry offsets it discovers and uses the indexed block starts. Compared with 4.0.13 and 4.2.4, a cold search in the benchmark sent about **90% fewer requests** to the object store (44 ranged reads instead of 428) and a nearby follow-up search about 96% fewer, which also means less data downloade [...]
 
 ### More reliable delivery and recovery {#more-reliable-delivery-and-recovery}
 
@@ -162,7 +146,7 @@ Reliability improvements strengthen the features existing applications use every
 - **Delayed delivery** fixes preserve message indexes through snapshot trimming and tracker recovery, and prevent premature replay.
 - **Acknowledgments and transactions** retain batch acknowledgment state and cursor properties during recovery, prevent already acknowledged messages from reaching dead-letter topics, and keep transactional and non-transactional messages in separate batches.
 
-Assignment and ownership cleanup fixes also improve recovery in the extensible load manager.
+Assignment and ownership cleanup fixes also improve recovery in the extensible load manager. Most of these fixes are also in the 4.0.14 and 4.2.5 maintenance releases.
 
 ## New capabilities {#new-capabilities}
 
@@ -172,23 +156,25 @@ Assignment and ownership cleanup fixes also improve recovery in the extensible l
 
 ### A Java client API built around how you consume {#v5-java-client}
 
-The [v5 Java client API](pathname:///docs/client-libraries/java-v5) gives applications three focused consumption models:
+Scalable Topics are used through the new [v5 Java client API](pathname:///docs/client-libraries/java-v5). Over more than a decade, Pulsar's client API grew one feature at a time, accumulating options, overloads, and subtle inconsistencies; the v5 API is a clean-slate redesign that distills the lessons from production use into a focused API.
+
+Consumption is the clearest example. The v4 client offers a single `Consumer` shaped by one of four subscription types (Exclusive, Failover, Shared, and Key_Shared), plus a separate `Reader`, with behavior that shifts as options are combined. The v5 API replaces them with three purpose-built consumers, each exposing only the operations that make sense for it:
 
-- **Stream consumers** for ordered consumption with cumulative acknowledgment.
-- **Queue consumers** for parallel processing with individual acknowledgments and dead-letter handling.
-- **Checkpoint consumers** for applications that manage their own processing position.
+- **Stream consumers** for ordered consumption with cumulative acknowledgment, including key-shared processing across consumers.
+- **Queue consumers** for parallel work-queue processing with individual and negative acknowledgments and dead-letter handling.
+- **Checkpoint consumers** for stream-processing engines such as Flink and Spark that track their own position, with no subscription or acknowledgment.
 
-The API supports Scalable Topics and existing persistent topics. Applications can also [subscribe across a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting topics by properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts efficiently.
+The v5 API also works with existing partitioned and non-partitioned persistent topics, so you can adopt it before converting any topic. Stream and queue consumers can also [subscribe to all scalable topics in a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting them by their properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts.
 
-**One dependency for the v4, v5, and admin clients.** For new applications or dependency updates, `org.apache.pulsar:pulsar-client-v5-all` provides all three through a single unshaded dependency with transitive dependencies. You can adopt it while continuing to use only the v4 API. See [Pulsar Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configuration) for complete Maven and Gradle examples, BOM alignment, and conflict exclusions, and the [API m [...]
+**One dependency for the v4, v5, and admin clients.** `org.apache.pulsar:pulsar-client-v5-all` contains the Java client, with both the v4 and v5 APIs, and the Java admin client. It is unshaded, so you can upgrade third-party dependencies yourself, for example to address CVEs, without waiting for a Pulsar release; import the Pulsar and Netty BOMs to keep their versions aligned, as described in [Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configu [...]
 
 The v5 API requires scalable-topic services to be enabled on the brokers, including for regular topics. The v4 API works whether those services are enabled or disabled, so application migration can follow the cluster upgrade on its own schedule.
 
 ### Oxia for new clusters, continuity for ZooKeeper deployments {#oxia-and-metadata-migration}
 
-[Oxia](https://oxia-db.github.io/) is fully open source under the [Apache-2.0 license](https://github.com/oxia-db/oxia/blob/main/LICENSE) and has been accepted into CNCF at the [Sandbox maturity level](https://www.cncf.io/projects/oxia/). It is the recommended metadata store for new clusters and the supported choice for Scalable Topics in production. Existing ZooKeeper deployments can continue running their workloads: with Scalable Topics disabled, all previously available features remai [...]
+[Oxia](https://oxia-db.github.io/) is fully open source under the [Apache-2.0 license](https://github.com/oxia-db/oxia/blob/main/LICENSE) and has been accepted into CNCF at the [Sandbox maturity level](https://www.cncf.io/projects/oxia/). It is the recommended metadata store for new Pulsar clusters and for Scalable Topics.
 
-When you choose to move to Oxia, the [metadata-store migration framework](administration-metadata-store-migration.md) copies metadata while publishing and consuming continue, with a planned cutover and validation procedure. You can schedule this separately from the software upgrade. ZooKeeper can also be used to test Scalable Topics in Pulsar 5.0.0; some scalable-topic features, including transactions, require Oxia.
+Existing ZooKeeper deployments can keep running unchanged. When you choose to move to Oxia, the [metadata store migration framework](administration-metadata-store-migration.md) ([PIP-454](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-454.md)) copies metadata while existing producers and consumers keep running; metadata changes such as topic creation and ledger rollovers pause during the copy. A planned cutover and validation procedure completes the move, which you can schedule sep [...]
 
 [Topic policies can now be stored directly in the metadata store](administration-metadata-store.md#store-topic-policies-in-the-metadata-store). Topics whose policies are stored in system topics keep using them, allowing operators to plan that transition separately as well.
 
diff --git a/src/css/docs.css b/src/css/docs.css
index 0361008deaa..69e6b0e362e 100644
--- a/src/css/docs.css
+++ b/src/css/docs.css
@@ -20,34 +20,6 @@
   margin-top: 0.5rem;
 }
 
-/* Distinguish benchmark changes in both light and dark themes. */
-.release-highlights-benchmark th:last-child,
-.release-highlights-benchmark td:last-child {
-  background-color: var(--primary-6);
-  color: var(--primary-5-);
-  border-left: 2px solid var(--color-primary);
-}
-
-[data-theme='dark'] .release-highlights-benchmark th:last-child,
-[data-theme='dark'] .release-highlights-benchmark td:last-child {
-  background-color: var(--primary-5-);
-  color: var(--primary-6);
-  border-left-color: var(--color-primary-dark);
-}
-
-/* Plain collapsible: drop the info-alert colors that Docusaurus adds to every <details>. */
-.details-plain.alert {
-  --ifm-alert-background-color: transparent;
-  --ifm-alert-background-color-highlight: var(--ifm-color-emphasis-100);
-  --ifm-alert-foreground-color: var(--ifm-font-color-base);
-  --ifm-alert-border-color: var(--ifm-color-emphasis-300);
-  --ifm-alert-border-left-width: var(--ifm-alert-border-width);
-  --ifm-link-color: var(--ifm-color-primary);
-  --ifm-link-hover-color: var(--ifm-color-primary-dark);
-  --ifm-link-decoration: none;
-  --docusaurus-details-decoration-color: var(--ifm-color-emphasis-600);
-}
-
 /* Use same blue color for NOTE admonition as for INFO */
 [class*="docs-doc-page"] .alert--secondary {
   --ifm-alert-background-color: var( --ifm-color-info-contrast-background );
diff --git a/static/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg b/static/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg
deleted file mode 100644
index 271b41b5337..00000000000
--- a/static/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg
+++ /dev/null
@@ -1,89 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1400 826">
-<rect width="100%" height="100%" fill="white"/>
-<style>text{font-family:DejaVu Sans,Arial,sans-serif;fill:#142b40}.muted{fill:#506275}</style>
-<text x="70" y="55" font-size="28" font-weight="bold">Latency by percentile</text>
-<text class="muted" x="70" y="82" font-size="15">Latency (ms), logarithmic scale · A: 4.0.13 · B: 5.0.0 · both panels have the same axes</text>
-<rect x="110" y="144" width="1240" height="230" fill="#ecf2fa"/>
-<line x1="110" y1="374" x2="1350" y2="374" stroke="#dae1e8"/>
-<text class="muted" x="100" y="378" text-anchor="end" font-size="12">0.1</text>
-<line x1="110" y1="341" x2="1350" y2="341" stroke="#dae1e8"/>
-<text class="muted" x="100" y="345" text-anchor="end" font-size="12">1</text>
-<line x1="110" y1="308" x2="1350" y2="308" stroke="#dae1e8"/>
-<text class="muted" x="100" y="312" text-anchor="end" font-size="12">10</text>
-<line x1="110" y1="275" x2="1350" y2="275" stroke="#dae1e8"/>
-<text class="muted" x="100" y="279" text-anchor="end" font-size="12">100</text>
-<line x1="110" y1="243" x2="1350" y2="243" stroke="#dae1e8"/>
-<text class="muted" x="100" y="247" text-anchor="end" font-size="12">1k</text>
-<line x1="110" y1="210" x2="1350" y2="210" stroke="#dae1e8"/>
-<text class="muted" x="100" y="214" text-anchor="end" font-size="12">10k</text>
-<line x1="110" y1="177" x2="1350" y2="177" stroke="#dae1e8"/>
-<text class="muted" x="100" y="181" text-anchor="end" font-size="12">100k</text>
-<line x1="110" y1="144" x2="1350" y2="144" stroke="#dae1e8"/>
-<text class="muted" x="100" y="148" text-anchor="end" font-size="12">1M</text>
-<line x1="110" y1="374" x2="110" y2="379" stroke="#142b40"/>
-<text x="110" y="394" text-anchor="middle" font-size="12">0%</text>
-<line x1="317" y1="374" x2="317" y2="379" stroke="#142b40"/>
-<text x="317" y="394" text-anchor="middle" font-size="12">90%</text>
-<line x1="523" y1="374" x2="523" y2="379" stroke="#142b40"/>
-<text x="523" y="394" text-anchor="middle" font-size="12">99%</text>
-<line x1="730" y1="374" x2="730" y2="379" stroke="#142b40"/>
-<text x="730" y="394" text-anchor="middle" font-size="12">99.9%</text>
-<line x1="937" y1="374" x2="937" y2="379" stroke="#142b40"/>
-<text x="937" y="394" text-anchor="middle" font-size="12">99.99%</text>
-<line x1="1143" y1="374" x2="1143" y2="379" stroke="#142b40"/>
-<text x="1143" y="394" text-anchor="middle" font-size="12">99.999%</text>
-<line x1="1350" y1="374" x2="1350" y2="379" stroke="#142b40"/>
-<text x="1350" y="394" text-anchor="middle" font-size="12">99.9999%</text>
-<line x1="110" y1="374" x2="1350" y2="374" stroke="#142b40"/>
-<text x="730" y="416" text-anchor="middle" font-size="12">Percentile</text>
-<polyline fill="none" stroke="#3465a4" stroke-width="1.5" stroke-linejoin="round" stroke-dasharray="9 6" points="110,329 119,247 130,247 142,247 156,247 172,247 182,246 192,246 204,246 218,246 234,246 244,246 254,246 266,246 280,246 297,246 306,245 317,245 329,244 342,244 359,244 368,244 379,244 391,244 405,244 421,244 431,243 441,243 453,243 467,243 483,243 493,243 503,243 515,243 529,243 545,243 555,243 566,243 578,243 591,243 608,243 617,243 628,243 640,243 654,243 670,243 679,243 690 [...]
-<polyline fill="none" stroke="#3465a4" stroke-width="1.5" stroke-linejoin="round" points="110,331 119,187 130,183 142,179 156,177 172,175 182,173 192,173 204,172 218,171 234,170 244,170 254,169 266,169 280,169 297,168 306,168 317,168 329,168 342,168 359,167 368,167 379,167 391,167 405,167 421,167 431,167 441,167 453,167 467,167 483,167 493,167 503,167 515,167 529,167 545,167 555,167 566,167 578,167 591,167 608,167 617,167 628,167 640,167 654,167 670,167 679,167 690,167 702,167 716,167 73 [...]
-<rect x="110" y="114" width="97" height="26" fill="#3465a4"/>
-<text x="122" y="132" font-size="14" font-weight="bold" style="fill:white">A: 4.0.13</text>
-<rect x="110" y="476" width="1240" height="230" fill="#fdf1e6"/>
-<line x1="110" y1="706" x2="1350" y2="706" stroke="#dae1e8"/>
-<text class="muted" x="100" y="710" text-anchor="end" font-size="12">0.1</text>
-<line x1="110" y1="673" x2="1350" y2="673" stroke="#dae1e8"/>
-<text class="muted" x="100" y="677" text-anchor="end" font-size="12">1</text>
-<line x1="110" y1="640" x2="1350" y2="640" stroke="#dae1e8"/>
-<text class="muted" x="100" y="644" text-anchor="end" font-size="12">10</text>
-<line x1="110" y1="607" x2="1350" y2="607" stroke="#dae1e8"/>
-<text class="muted" x="100" y="611" text-anchor="end" font-size="12">100</text>
-<line x1="110" y1="575" x2="1350" y2="575" stroke="#dae1e8"/>
-<text class="muted" x="100" y="579" text-anchor="end" font-size="12">1k</text>
-<line x1="110" y1="542" x2="1350" y2="542" stroke="#dae1e8"/>
-<text class="muted" x="100" y="546" text-anchor="end" font-size="12">10k</text>
-<line x1="110" y1="509" x2="1350" y2="509" stroke="#dae1e8"/>
-<text class="muted" x="100" y="513" text-anchor="end" font-size="12">100k</text>
-<line x1="110" y1="476" x2="1350" y2="476" stroke="#dae1e8"/>
-<text class="muted" x="100" y="480" text-anchor="end" font-size="12">1M</text>
-<line x1="110" y1="706" x2="110" y2="711" stroke="#142b40"/>
-<text x="110" y="726" text-anchor="middle" font-size="12">0%</text>
-<line x1="317" y1="706" x2="317" y2="711" stroke="#142b40"/>
-<text x="317" y="726" text-anchor="middle" font-size="12">90%</text>
-<line x1="523" y1="706" x2="523" y2="711" stroke="#142b40"/>
-<text x="523" y="726" text-anchor="middle" font-size="12">99%</text>
-<line x1="730" y1="706" x2="730" y2="711" stroke="#142b40"/>
-<text x="730" y="726" text-anchor="middle" font-size="12">99.9%</text>
-<line x1="937" y1="706" x2="937" y2="711" stroke="#142b40"/>
-<text x="937" y="726" text-anchor="middle" font-size="12">99.99%</text>
-<line x1="1143" y1="706" x2="1143" y2="711" stroke="#142b40"/>
-<text x="1143" y="726" text-anchor="middle" font-size="12">99.999%</text>
-<line x1="1350" y1="706" x2="1350" y2="711" stroke="#142b40"/>
-<text x="1350" y="726" text-anchor="middle" font-size="12">99.9999%</text>
-<line x1="110" y1="706" x2="1350" y2="706" stroke="#142b40"/>
-<text x="730" y="748" text-anchor="middle" font-size="12">Percentile</text>
-<polyline fill="none" stroke="#d65f00" stroke-width="1.5" stroke-linejoin="round" stroke-dasharray="9 6" points="110,677 119,577 130,576 142,576 156,576 172,576 182,576 192,576 204,575 218,575 234,575 244,575 254,575 266,575 280,575 297,575 306,574 317,574 329,574 342,574 359,574 368,574 379,574 391,574 405,574 421,574 431,574 441,574 453,574 467,573 483,573 493,573 503,573 515,573 529,573 545,573 555,573 566,573 578,573 591,573 608,573 617,573 628,573 640,573 654,573 670,573 679,573 690 [...]
-<polyline fill="none" stroke="#d65f00" stroke-width="1.5" stroke-linejoin="round" points="110,673 119,577 130,576 142,576 156,576 172,576 182,576 192,575 204,575 218,575 234,575 244,575 254,575 266,575 280,575 297,574 306,574 317,574 329,574 342,574 359,574 368,574 379,574 391,574 405,574 421,574 431,574 441,574 453,574 467,574 483,573 493,573 503,573 515,573 529,573 545,573 555,573 566,573 578,573 591,573 608,573 617,573 628,573 640,573 654,573 670,573 679,573 690,573 702,573 716,573 73 [...]
-<rect x="110" y="446" width="89" height="26" fill="#d65f00"/>
-<text x="122" y="464" font-size="14" font-weight="bold" style="fill:white">B: 5.0.0</text>
-<line x1="110" y1="781" x2="138" y2="781" stroke="#3465a4" stroke-width="1.5" stroke-dasharray="9 6"/>
-<text x="146" y="786" font-size="14">A: Publish</text>
-<line x1="244" y1="781" x2="272" y2="781" stroke="#3465a4" stroke-width="1.5"/>
-<text x="280" y="786" font-size="14">A: End-to-end</text>
-<line x1="401" y1="781" x2="429" y2="781" stroke="#d65f00" stroke-width="1.5" stroke-dasharray="9 6"/>
-<text x="437" y="786" font-size="14">B: Publish</text>
-<line x1="535" y1="781" x2="563" y2="781" stroke="#d65f00" stroke-width="1.5"/>
-<text x="571" y="786" font-size="14">B: End-to-end</text>
-<text class="muted" x="1388" y="814" text-anchor="end" font-size="10">A: 4.0.13 10-01-14-59-33    B: 5.0.0 10-01-15-14-58</text>
-</svg>
diff --git a/static/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg b/static/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg
deleted file mode 100644
index 8dfa3c6a038..00000000000
--- a/static/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg
+++ /dev/null
@@ -1,107 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1400 762">
-<rect width="100%" height="100%" fill="white"/>
-<style>text{font-family:DejaVu Sans,Arial,sans-serif;fill:#142b40}.muted{fill:#506275}</style>
-<text x="70" y="55" font-size="28" font-weight="bold">Seek by timestamp on offloaded ledgers</text>
-<text class="muted" x="70" y="82" font-size="15">Ranged reads sent to the object store per search, mean of 16 searches · both panels have the same axis</text>
-<rect x="470" y="114" width="125" height="26" fill="#142b40"/>
-<text x="482" y="132" font-size="14" font-weight="bold" style="fill:white">Cold search</text>
-<rect x="470" y="144" width="880" height="198" fill="#f1f4f7"/>
-<line x1="470" y1="144" x2="470" y2="342" stroke="#dae1e8"/>
-<line x1="470" y1="342" x2="470" y2="347" stroke="#142b40"/>
-<text x="470" y="362" text-anchor="middle" font-size="12">0</text>
-<line x1="568" y1="144" x2="568" y2="342" stroke="#dae1e8"/>
-<line x1="568" y1="342" x2="568" y2="347" stroke="#142b40"/>
-<text x="568" y="362" text-anchor="middle" font-size="12">50</text>
-<line x1="666" y1="144" x2="666" y2="342" stroke="#dae1e8"/>
-<line x1="666" y1="342" x2="666" y2="347" stroke="#142b40"/>
-<text x="666" y="362" text-anchor="middle" font-size="12">100</text>
-<line x1="763" y1="144" x2="763" y2="342" stroke="#dae1e8"/>
-<line x1="763" y1="342" x2="763" y2="347" stroke="#142b40"/>
-<text x="763" y="362" text-anchor="middle" font-size="12">150</text>
-<line x1="861" y1="144" x2="861" y2="342" stroke="#dae1e8"/>
-<line x1="861" y1="342" x2="861" y2="347" stroke="#142b40"/>
-<text x="861" y="362" text-anchor="middle" font-size="12">200</text>
-<line x1="959" y1="144" x2="959" y2="342" stroke="#dae1e8"/>
-<line x1="959" y1="342" x2="959" y2="347" stroke="#142b40"/>
-<text x="959" y="362" text-anchor="middle" font-size="12">250</text>
-<line x1="1057" y1="144" x2="1057" y2="342" stroke="#dae1e8"/>
-<line x1="1057" y1="342" x2="1057" y2="347" stroke="#142b40"/>
-<text x="1057" y="362" text-anchor="middle" font-size="12">300</text>
-<line x1="1154" y1="144" x2="1154" y2="342" stroke="#dae1e8"/>
-<line x1="1154" y1="342" x2="1154" y2="347" stroke="#142b40"/>
-<text x="1154" y="362" text-anchor="middle" font-size="12">350</text>
-<line x1="1252" y1="144" x2="1252" y2="342" stroke="#dae1e8"/>
-<line x1="1252" y1="342" x2="1252" y2="347" stroke="#142b40"/>
-<text x="1252" y="362" text-anchor="middle" font-size="12">400</text>
-<line x1="1350" y1="144" x2="1350" y2="342" stroke="#dae1e8"/>
-<line x1="1350" y1="342" x2="1350" y2="347" stroke="#142b40"/>
-<text x="1350" y="362" text-anchor="middle" font-size="12">450</text>
-<line x1="470" y1="144" x2="470" y2="342" stroke="#142b40"/>
-<line x1="470" y1="342" x2="1350" y2="342" stroke="#142b40"/>
-<text x="910" y="384" text-anchor="middle" font-size="12">Ranged reads per search</text>
-<text x="456" y="179" text-anchor="end" font-size="14">Before these changes</text>
-<rect x="470" y="163" width="837" height="22" fill="#3465a4"/>
-<text x="1315" y="179" font-size="14" font-weight="bold">428</text>
-<text x="456" y="225" text-anchor="end" font-size="14">+ offsets found while scanning are reused</text>
-<rect x="470" y="209" width="305" height="22" fill="#d65f00"/>
-<text x="783" y="225" font-size="14" font-weight="bold">156</text>
-<text x="456" y="271" text-anchor="end" font-size="14">+ search reads the first entry of data blocks</text>
-<rect x="470" y="255" width="119" height="22" fill="#d65f00"/>
-<text x="597" y="271" font-size="14" font-weight="bold">61</text>
-<text x="456" y="317" text-anchor="end" font-size="14">+ offsets are remembered per ledger (5.0.0)</text>
-<rect x="470" y="301" width="86" height="22" fill="#d65f00"/>
-<text x="564" y="317" font-size="14" font-weight="bold">44</text>
-<rect x="470" y="414" width="125" height="26" fill="#142b40"/>
-<text x="482" y="432" font-size="14" font-weight="bold" style="fill:white">Warm search</text>
-<rect x="470" y="444" width="880" height="198" fill="#f1f4f7"/>
-<line x1="470" y1="444" x2="470" y2="642" stroke="#dae1e8"/>
-<line x1="470" y1="642" x2="470" y2="647" stroke="#142b40"/>
-<text x="470" y="662" text-anchor="middle" font-size="12">0</text>
-<line x1="568" y1="444" x2="568" y2="642" stroke="#dae1e8"/>
-<line x1="568" y1="642" x2="568" y2="647" stroke="#142b40"/>
-<text x="568" y="662" text-anchor="middle" font-size="12">50</text>
-<line x1="666" y1="444" x2="666" y2="642" stroke="#dae1e8"/>
-<line x1="666" y1="642" x2="666" y2="647" stroke="#142b40"/>
-<text x="666" y="662" text-anchor="middle" font-size="12">100</text>
-<line x1="763" y1="444" x2="763" y2="642" stroke="#dae1e8"/>
-<line x1="763" y1="642" x2="763" y2="647" stroke="#142b40"/>
-<text x="763" y="662" text-anchor="middle" font-size="12">150</text>
-<line x1="861" y1="444" x2="861" y2="642" stroke="#dae1e8"/>
-<line x1="861" y1="642" x2="861" y2="647" stroke="#142b40"/>
-<text x="861" y="662" text-anchor="middle" font-size="12">200</text>
-<line x1="959" y1="444" x2="959" y2="642" stroke="#dae1e8"/>
-<line x1="959" y1="642" x2="959" y2="647" stroke="#142b40"/>
-<text x="959" y="662" text-anchor="middle" font-size="12">250</text>
-<line x1="1057" y1="444" x2="1057" y2="642" stroke="#dae1e8"/>
-<line x1="1057" y1="642" x2="1057" y2="647" stroke="#142b40"/>
-<text x="1057" y="662" text-anchor="middle" font-size="12">300</text>
-<line x1="1154" y1="444" x2="1154" y2="642" stroke="#dae1e8"/>
-<line x1="1154" y1="642" x2="1154" y2="647" stroke="#142b40"/>
-<text x="1154" y="662" text-anchor="middle" font-size="12">350</text>
-<line x1="1252" y1="444" x2="1252" y2="642" stroke="#dae1e8"/>
-<line x1="1252" y1="642" x2="1252" y2="647" stroke="#142b40"/>
-<text x="1252" y="662" text-anchor="middle" font-size="12">400</text>
-<line x1="1350" y1="444" x2="1350" y2="642" stroke="#dae1e8"/>
-<line x1="1350" y1="642" x2="1350" y2="647" stroke="#142b40"/>
-<text x="1350" y="662" text-anchor="middle" font-size="12">450</text>
-<line x1="470" y1="444" x2="470" y2="642" stroke="#142b40"/>
-<line x1="470" y1="642" x2="1350" y2="642" stroke="#142b40"/>
-<text x="910" y="684" text-anchor="middle" font-size="12">Ranged reads per search</text>
-<text x="456" y="479" text-anchor="end" font-size="14">Before these changes</text>
-<rect x="470" y="463" width="436" height="22" fill="#3465a4"/>
-<text x="914" y="479" font-size="14" font-weight="bold">223</text>
-<text x="456" y="525" text-anchor="end" font-size="14">+ offsets found while scanning are reused</text>
-<rect x="470" y="509" width="27" height="22" fill="#d65f00"/>
-<text x="505" y="525" font-size="14" font-weight="bold">14</text>
-<text x="456" y="571" text-anchor="end" font-size="14">+ search reads the first entry of data blocks</text>
-<rect x="470" y="555" width="18" height="22" fill="#d65f00"/>
-<text x="496" y="571" font-size="14" font-weight="bold">9</text>
-<text x="456" y="617" text-anchor="end" font-size="14">+ offsets are remembered per ledger (5.0.0)</text>
-<rect x="470" y="601" width="18" height="22" fill="#d65f00"/>
-<text x="496" y="617" font-size="14" font-weight="bold">9</text>
-<rect x="110" y="704" width="28" height="14" fill="#3465a4"/>
-<text x="146" y="716" font-size="14">Before these changes</text>
-<rect x="330" y="704" width="28" height="14" fill="#d65f00"/>
-<text x="366" y="716" font-size="14">After each change</text>
-<text class="muted" x="1388" y="750" text-anchor="end" font-size="10">OffloadedLedgerFindPositionTest · 64 MiB data blocks · 1 MiB read buffer · in-memory object store</text>
-</svg>
diff --git a/versioned_docs/version-5.0.x/release-highlights.md b/versioned_docs/version-5.0.x/release-highlights.md
index 10237f30a51..a6f97d143fe 100644
--- a/versioned_docs/version-5.0.x/release-highlights.md
+++ b/versioned_docs/version-5.0.x/release-highlights.md
@@ -9,14 +9,14 @@ import ReleaseSeriesNotes from '@site/src/components/ReleaseSeriesNotes';
 
 Pulsar 5.0 introduces **Scalable Topics** for applications that need to grow beyond a fixed partition count, alongside **major performance and reliability improvements for existing workloads**. Scale topics and consumers as demand changes, benefit from more efficient brokers, and keep the applications and topics you already run.
 
-- **Scalable Topics: grow beyond a fixed partition count.** Traditional partitions cannot shrink, and adding partitions can disrupt per-key ordering. Sizing too generously wastes resources; sizing too narrowly creates hot partitions and costly migrations. Scalable Topics let you split and merge key ranges and scale consumers while preserving per-key ordering and producer batching.
-- **More performance from existing workloads.** Fewer thread handoffs, less contention, and batched storage reads reduce the work behind each message. In one [many-publisher benchmark](#keep-consumers-at-the-tail-with-many-publishers), backlog growth during publishing fell from **128,585 to 173 messages/s (−99.9%)**, and the maximum backlog fell by **99.7%**. In this workload, consumers stayed at the tail with hundreds of publishers without accumulating a sustained backlog.
+- **Scalable Topics: topics that size themselves.** Instead of choosing a partition count up front, a scalable topic splits hot key-range segments and merges cold ones at runtime, while preserving per-key ordering and producer batching.
+- **More performance from existing workloads.** Fewer thread handoffs, less contention, and batched storage reads reduce the work behind each message. In a [benchmark with 500 publishers](#keep-consumers-at-the-tail-with-many-publishers), consumers stayed at the tail instead of stalling behind the producers, the broker sustained about **1.7× the total load**, published plus consumed, and p99 end-to-end latency fell from **202.3 s to 1.08 s**.
 - **More dependable delivery.** Fixes across geo-replication, subscriptions, delayed delivery, and acknowledgment recovery address stalls in the features applications use every day.
 - **Easier operation at scale.** Better load distribution, coordinated rolling-upgrade guidance, structured logs, and the ability to close idle topics without deleting their data give operators more control.
 
 :::tip Upgrade with confidence
 
-**Keep your applications and topics.** Existing partitioned and non-partitioned topics, subscription types, and the existing Java client—now called the **v4 client**—remain supported. Your v4 applications can keep their client dependency and API when you upgrade the cluster. With Scalable Topics disabled, all previously available features remain fully supported in production on ZooKeeper.
+**Keep your applications and topics.** Existing partitioned and non-partitioned topics, subscription types, and the existing Java client—now called the **v4 client**—remain supported. Your v4 applications can keep their client dependency and API when you upgrade the cluster. ZooKeeper remains fully supported as the metadata store.
 
 **Adopt new capabilities on your schedule.** The v5 client API, Scalable Topics, and Oxia are separate choices. Upgrade your cluster first, then introduce the capabilities that suit your applications.
 
@@ -32,126 +32,110 @@ Pulsar 5.0 introduces **Scalable Topics** for applications that need to grow bey
 
 <!-- Release-note links update automatically. Retain this page's stable document ID. -->
 
-## Scalable Topics {#scalable-topics}
+## Scalable Topics: topics that size themselves {#scalable-topics}
 
-[Scalable Topics](concepts-scalable-topics.md) give applications a logical topic that can grow as demand changes. Key-range segments can split and merge, so applications use a `topic://` address without managing a partition count.
+A topic should be a **logical concept**: a named stream that applications publish to and consume from. Yet for its whole history, Pulsar has asked application developers to answer an infrastructure question up front: **how many partitions?** That number is a guess that is easy to get wrong and hard to undo. It is chosen before you know the real traffic, it can be increased but never decreased, and because keys are routed with `hash(key) % partitionCount`, increasing it moves keys to diff [...]
 
-Consumer parallelism can grow within each segment, too. Multiple consumers share the work while preserving per-key ordering, including when consumers join or leave. This helps drain backlogs left in segments after they split or merge and lets applications keep producer batching enabled without selecting a key-based batcher for this consumption mode.
+**[Scalable Topics](concepts-scalable-topics.md) take that decision away.** A scalable topic, addressed with the new `topic://` scheme, is a single logical stream whose capacity follows its actual load, in both directions:
 
-Existing persistent topics can be [migrated in place](admin-api-scalable-topics.md#migrate-a-regular-topic), without copying their data, after their producers and consumers move to the v5 client. [Transactions](txn-use.md#transactions-on-scalable-topics) work across segment splits and merges when enabled on brokers using Oxia. In production, Scalable Topics use Oxia; ZooKeeper deployments can try them in test environments. The [administration guide](admin-api-scalable-topics.md) covers s [...]
+- **Key-range segments.** The key hash space is divided into segments, each owning a contiguous range and backed by its own internal topic.
+- **Split and merge at runtime.** The broker splits hot segments and merges adjacent cold ones with no downtime. This is automatic by default, with thresholds you can tune per broker, namespace, and topic, and you can also split and merge manually.
+- **Per-key ordering is preserved.** A split or merge moves a key to a successor range that still contains it, and stream consumers drain the predecessor segment before reading its successor.
+- **Applications see one stream.** A per-topic controller in the broker manages the segment layout and pushes changes to clients, so applications never handle segments or react to resizing.
 
-Operators can keep Scalable Topics behind a feature gate during the upgrade by setting `scalableTopicsEnabled=false` on every target broker before the first 5.0 broker starts. Together with the other [rollback prerequisites](administration-upgrade-to-5.0.x.md#preserve-and-rehearse-rollback), this preserves a safe path back to the tested 4.x release if problems arise during the 5.x upgrade. Enable the feature in production when you are ready, after validating the upgraded cluster and clos [...]
+Consumer parallelism can grow within a segment, too. Messages are grouped into **entry buckets** by key hash, and multiple stream consumers share a segment's buckets in key order, including when consumers join or leave. When more consumers join, Pulsar can split a busy segment or give it more buckets, and after a split or merge, consumers share the sealed segment's buckets to drain its backlog. **If you have struggled to combine Key_Shared subscriptions with producer batching, this addre [...]
 
-## Performance and reliability {#performance-and-reliability}
+| | Partitioned topic (v4) | Scalable topic |
+| --- | --- | --- |
+| Capacity | Partition count chosen at creation | Segments and entry buckets that change at runtime |
+| Scale up | Increase the partition count manually | Hot segments split automatically |
+| Scale down | Not possible | Cold segments merge automatically |
+| Key ordering when resized | Keys can move between partitions | Preserved across splits and merges for stream consumers |
+| Layout visible to applications | Partition count and indexes | None; managed by the broker |
 
-:::tip
-
-The performance and reliability improvements in Pulsar 5.0 apply to existing applications and topics. They don't require adopting Scalable Topics or the v5 client API. After [upgrading from Pulsar 4.x](administration-upgrade-to-5.0.x.md), existing applications continue to work with all their current features and benefit from these improvements without code changes.
-
-:::
-
-### Keep consumers at the tail with 100s of publishers {#keep-consumers-at-the-tail-with-many-publishers}
+The goal is for one topic type to be the right choice across use cases, out of the box: you model your application around the topics that fit your domain, and Pulsar adapts them to how they are actually used, without capacity planning or re-sharding.
 
-In a typical IoT deployment, hundreds of thousands of devices connect to hundreds of gateways, and each gateway publishes the devices' telemetry to Pulsar, which serves as the message bus for the applications that process it. The messages are keyed by device ID, so that each device's messages are processed in order, and for that reason they usually aren't batched. Pulsar 5.0 reduces the broker queueing and contention that could make the consuming applications fall behind even when they w [...]
+Scalable Topics are delivered by a family of Pulsar Improvement Proposals:
 
-A benchmark compared Pulsar 4.0.13 and 5.0.0 in a simplified version of this use case:
+- **[PIP-460](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-460.md)**: Scalable Topics, the overall model
+- **[PIP-468](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-468.md)**: the per-topic controller
+- **[PIP-483](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-483.md)**: automatic split and merge
+- **[PIP-486](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-486.md)**: key-shared consumption with entry buckets
+- **[PIP-466](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-466.md)**: the v5 Java client API
+- **[PIP-473](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-473.md)**: transactions across splits and merges
+- **[PIP-475](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-475.md)**: in-place migration of regular topics, with no data copy
+- **[PIP-494](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-494.md)**: the client specification and its change process
+- **[PIP-496](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-496.md)**: Functions and IO connectors on Scalable Topics
 
-- **500 gateways** publish keyed, unbatched 128-byte messages to one shared topic, as fast as the cluster accepts them.
-- **20 instances of a message-processing application** consume them from that topic on one Key_Shared subscription, which delivers each key's messages in order to one instance at a time.
-- Each gateway and each application instance has its own Pulsar client and TCP connection.
+### A client specification for every SDK {#scalable-topics-client-specification}
 
-The results:
+With Scalable Topics, clients do more than connect to a topic: they track the segment layout as it changes, route each key to the segment that owns it, and follow the controller's consumer assignments. To make every client behave the same way, Pulsar 5.0 ships the **[Scalable Topics Client Specification](https://github.com/apache/pulsar/tree/v5.0.0/spec/scalable-topics) 1.0**, the authoritative, language-neutral contract for Scalable Topics clients:
 
-<div className="release-highlights-benchmark">
+- **One contract for all languages.** It separates the API contract that applications observe from a client's internal mechanisms and the exact wire-protocol interactions, documented with sequence diagrams. Conformant clients route keys identically and share ordering and acknowledgment semantics, so producers and consumers written in different languages can work on the same scalable topic.
+- **Stable and versioned.** Each feature has a stability tier. Incompatible changes land only at an LTS boundary, deprecated features remain available at least until the next LTS release, and every normative change goes through a PIP together with its specification edits.
+- **A clear definition of support.** A conformance checklist defines what an SDK must implement to claim Scalable Topics support. The Java v5 client is the reference implementation, while the specification is the source of truth.
 
-| Means of 3 runs | 4.0.13 | 5.0.0 | Change |
-| --- | ---: | ---: | ---: |
-| Publishing rate, messages/s | 128,716 | 107,048 | −16.8% |
-| Consuming rate during publishing, messages/s | 131 | 106,875 | ×816 |
-| **Backlog growth rate during publishing, messages/s** | **128,585** | **173** | **−99.9%** |
-| Delivered throughput, until the last message arrived, messages/s | 17,038 | 106,658 | +526% |
-| Time the consumers needed after publishing ended | 202–205 s | 0 s | |
-| **Maximum backlog, messages** | **3,990,044** | **12,729** | **−99.7%** |
-| End-to-end latency, p99 | 202.3 s | 1.08 s | −99.5% |
+Today, the Java [v5 client](#v5-java-client) supports Scalable Topics, and work is ongoing to bring that support to the other Pulsar client SDKs.
 
-</div>
+### Adopting Scalable Topics {#adopting-scalable-topics}
 
-**Backlog growth rate during publishing** is **publishing rate − consumption rate during publishing**, or equivalently **(messages published − messages consumed by the time all publishers finished) ÷ publishing duration in seconds**. A lower value means consumers keep closer to the publishers.
+- **New applications** are encouraged to build on Scalable Topics and the v5 API when the [requirements and limitations](concepts-scalable-topics.md#requirements) fit.
+- **Existing applications** can keep their partitioned and non-partitioned topics, with no requirement to migrate. When you're ready, existing persistent topics can be [migrated in place](admin-api-scalable-topics.md#migrate-a-regular-topic), without copying their data, once their producers and consumers use the v5 client. The conversion is one-way.
+- **Requirements:** a client with v5 API support, since v4 clients cannot use `topic://` topics, and scalable-topic services enabled on the brokers, which the v5 API needs even for regular topics. Scalable Topics work with ZooKeeper and Oxia, with Oxia recommended, and support [transactions](txn-use.md#transactions-on-scalable-topics) across segment splits and merges.
+- **Functions and IO connectors:** Java Functions and IO connectors switch to the v5 client automatically when their topics are `topic://` topics. Python and Go Functions keep the v4 client and cannot use `topic://` topics.
+- **Limitations:** geo-replication and replicated subscriptions are not supported for Scalable Topics in 5.0. Use partitioned or non-partitioned topics for applications that need them.
 
-**Delivered throughput** is calculated for each run as **4,000,000 messages ÷ elapsed seconds from the start of publishing until the last message was consumed**, including any time spent draining the backlog after publishing ended. The table reports the mean of the three runs.
+Operators can keep Scalable Topics behind a feature gate during the upgrade by setting `scalableTopicsEnabled=false` (the default is `true`) on every target broker before the first 5.0 broker starts. Together with the other [rollback prerequisites](administration-upgrade-to-5.0.x.md#preserve-and-rehearse-rollback), this preserves a safe path back to the tested 4.x release if problems arise during the 5.x upgrade. Enable the feature in production when you are ready, after validating the u [...]
 
-What the results show:
+The v4 API and existing topic types remain fully supported throughout the 5.0 LTS line. Longer term, Scalable Topics are designed to cover all of Pulsar's use cases, and the v5 API is the direction Pulsar is heading; according to [PIP-460](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-460.md), any deprecation of the existing API would be planned for a later LTS release.
 
-- **4.0.13's consumers fell behind:** they received almost nothing while the producers published, and needed more than 200 s afterwards to catch up.
-- **5.0.0's consumers kept up:** they received the messages as fast as they were published, about 1 s after publishing at p99.
-- **4.0.13 published faster** because its broker was hardly delivering anything at the same time, while 5.0.0's broker did both.
+To get started, read the [Scalable Topics concepts](concepts-scalable-topics.md), the [v5 Java client guide](pathname:///docs/client-libraries/java-v5), and [Manage scalable topics](admin-api-scalable-topics.md).
 
-Throughput of one run of each version, each in a panel of its own with the same axes. With 4.0.13, consumption (the solid line) stays near zero until publishing ends, then drains the backlog at about 20,000 messages/s for more than 200 s; with 5.0.0, it follows publishing (the dashed line):
-
-![Throughput of Pulsar 4.0.13 and 5.0.0: published and consumed messages per second, in separate panels with the same axes](/assets/release-highlights-5.0/throughput-4.0.13-vs-5.0.0-separate.svg)
-
-Publish and end-to-end latency by percentile, on a logarithmic scale. The publish latencies are similar, about 1 s, while 4.0.13's end-to-end latency reaches about 200 s:
-
-![Latency by percentile of Pulsar 4.0.13 and 5.0.0 on a logarithmic scale, in separate panels with the same axes](/assets/release-highlights-5.0/latency-percentiles-log-4.0.13-vs-5.0.0-separate.svg)
-
-For these **tailing reads**—consuming newly published messages near the end of the topic—fewer thread handoffs and batched publish submission let dispatch keep moving instead of waiting behind one executor task per entry.
-
-How it was measured:
+## Performance and reliability for existing workloads {#performance-and-reliability}
 
-- [Pulsar's performance testing framework](https://github.com/apache/pulsar/tree/master/tests/performance) ran its [`iot-telemetry-max-rate`](https://github.com/apache/pulsar/blob/master/tests/performance/scenarios/iot-telemetry-max-rate.yaml) scenario, with single-copy ledgers on three bookies, on one 8-core host at a fixed 2.4 GHz.
-- Each run measured 4 million messages after a warmup. With 4.0.13, publishing took about 31 s and the last message arrived after about 235 s; with 5.0.0, both took about 37 s.
-- The topic was a regular persistent topic, not a Scalable Topic, so that both versions ran the same kind of topic and the comparison with 4.0.13 is like for like.
-- 4.0.13 ran with its own defaults, and both versions used the same 5.0.0 client. Every run delivered every message without duplicates or ordering violations.
-
-The results describe this workload, not general broker capacity: run the scenario on your own hardware to compare with your application. Consumers still need enough processing capacity to keep up with producers.
-
-### Seek by timestamp in offloaded topics with fewer object store requests {#seek-by-timestamp-in-offloaded-topics}
-
-Topics with long retention, for example 1 year, hold most of their history in [tiered storage](tiered-storage-overview.md). Seeking such a topic to a timestamp runs a binary search over its offloaded ledgers, but their index records only the first entry of each data block, so reaching any other entry meant scanning the block from its start, one ranged read at a time. Pulsar 5.0 remembers the entry offsets it finds and makes use of the indexed block starts, so a search sends about **90% f [...]
+:::tip
 
-<div className="release-highlights-benchmark">
+The performance and reliability improvements in Pulsar 5.0 apply to existing applications and topics. They don't require adopting Scalable Topics or the v5 client API. After [upgrading from Pulsar 4.x](administration-upgrade-to-5.0.x.md), existing applications continue to work with all their current features and benefit from these improvements without code changes.
 
-| Ranged reads per search, 1 MiB each | Before | 5.0.0 | Change |
-| --- | ---: | ---: | ---: |
-| **Cold search, mean of 16 searches** | **428** | **44** | **−90%** |
-| Warm search, mean of 16 searches | 223 | 9 | −96% |
-| Cold search, maximum | 738 | 70 | −91% |
+:::
 
-</div>
+### Consumers keep up with hundreds of publishers {#keep-consumers-at-the-tail-with-many-publishers}
 
-A **cold search** runs with no entry offset cached; a **warm search** follows it and seeks 200 entries earlier, as when a consumer seeks again nearby. **Before** is Pulsar 4.0.13 and 4.2.4.
+In a typical IoT deployment, devices connect to hundreds of gateways that publish the devices' telemetry to Pulsar. Messages are keyed by device ID so that each device's messages are processed in order, and for that reason they are often not batched.
 
-![Ranged reads sent to the object store per search by timestamp on offloaded ledgers, before the changes and after each of the three changes, for cold and warm searches in separate panels with the same axis](/assets/release-highlights-5.0/seek-by-timestamp-offloaded-ranged-reads.svg)
+A benchmark compared Pulsar 4.0.13 and 5.0.0 on a simplified version of this use case: **500 publishers** sent keyed, unbatched 128-byte messages, as fast as the broker accepted them, to one regular persistent topic, consumed by **20 consumers** on one Key_Shared subscription. Each publisher and consumer had its own client and connection, and both versions were driven by the same 5.0.0 Java client. The table shows the means of three runs.
 
-The figures count requests and bytes, not latency, which depends on your object store. See [read performance for object storage](tiered-storage-overview.md#read-performance-for-object-storage) for the settings involved, and the [message position search metrics](reference-metrics-opentelemetry.md#message-position-search-metrics) to observe searches on a running broker.
+| | 4.0.13 | 5.0.0 |
+| --- | ---: | ---: |
+| Publishing rate, messages/s | 128,716 | 107,048 |
+| Consuming rate during publishing, messages/s | 131 | 106,875 |
+| Published + consumed, messages/s | 128,847 | 213,923 |
+| End-to-end latency, p99 | 202.3 s | 1.08 s |
 
-<details className="details-plain">
-<summary>Offloaded-ledger seek improvements in detail and how they were measured</summary>
+Once the broker reached its CPU limit, contention between threads in 4.0.13 left the consumers stalled behind the producers: they received almost nothing until publishing ended, and the backlog grew to almost 4 million messages. 4.0.13 accepted messages faster only because it was barely delivering any. Pulsar 5.0.0 shares the broker fairly between publishing and dispatch, so consumers stay at the tail and it sustains about **1.7× the total load**, published plus consumed.
 
-What each change contributes:
+![Throughput of one run of Pulsar 4.0.13 and of 5.0.0: published and consumed messages per second, in separate panels with the same axes](/assets/release-highlights-5.0/throughput-4.0.13-vs-5.0.0-separate.svg)
 
-- **Entry offsets found while scanning are reused:** a scan caches the offset of every entry it passes, and a later read starts from a nearby cached offset instead of the start of the block. Cold searches go from 428 to 156 ranged reads, and warm searches from 223 to 14.
-- **The search reads the first entry of data blocks:** when the first entry of a data block is close to the midpoint of the search range, the search reads that entry instead, with a single ranged read. Cold searches go from 156 to 61, and warm searches from 14 to 9.
-- **Offsets are remembered for each open ledger:** scans keep offsets about 1 MiB apart for as long as the offloaded ledger stays open, and later reads in the same data block resume from the nearest one. Cold searches go from 61 to 44, and warm searches stay at 9.
+The gains come mainly from fewer thread handoffs and batched publish submission, which keep dispatch moving instead of waiting behind one executor task per entry. These results describe this workload, not general broker capacity. Consumers still need enough processing capacity to keep up with producers.
 
 How it was measured:
 
-- The topic held about 130,000 entries of 2 to 6 KiB in two offloaded ledgers of about 250 MiB each, with 64 MiB data blocks and a 1 MiB read buffer.
-- [`OffloadedLedgerFindPositionTest`](https://github.com/apache/pulsar/blob/master/tiered-storage/jcloud/src/test/java/org/apache/bookkeeper/mledger/offload/jcloud/impl/OffloadedLedgerFindPositionTest.java) ran before the first change and after each change, with its data set to this layout. As committed, the test uses 16 MiB data blocks and one ledger to stay small.
-- The object store was in memory, and the broker entry cache was disabled so that every entry read reached the offloaded ledger.
-- The 16 searched positions are spread over both ledgers and over the positions within their data blocks. Each search covers both ledgers; a seek first narrows the search to the ledgers that can contain the timestamp.
-
-</details>
+- [Pulsar's performance testing framework](https://github.com/apache/pulsar/tree/v5.0.0/tests/performance) ran its [`iot-telemetry-max-rate`](https://github.com/apache/pulsar/blob/v5.0.0/tests/performance/scenarios/iot-telemetry-max-rate.yaml) scenario, with single-copy ledgers on three bookies, on one 8-core host at a fixed 2.4 GHz. You can run the scenario on your own hardware to compare with your application.
+- Each run measured 4 million messages after a warmup. With 4.0.13, publishing took about 31 s and the last message arrived after about 235 s; with 5.0.0, both took about 37 s.
+- The topic was a regular persistent topic, not a Scalable Topic, so that both versions ran the same kind of topic and the comparison with 4.0.13 is like for like. 4.0.13 ran with its own defaults. Every run delivered every message without duplicates or ordering violations.
+- **Consuming rate during publishing** counts the messages consumed by the time all publishers finished, divided by the publishing duration. **Published + consumed** is the sum of the publishing rate and the consuming rate during publishing, the total message load the broker handled while publishing.
 
 ### Less work per message {#less-work-per-message}
 
-The efficiency improvements reach across the messaging path:
+- **Publishing and dispatch:** batched handovers reduce executor contention, producers on a topic with deduplication enabled no longer contend on a topic-wide lock, and Shared and Key_Shared dispatch use fewer synchronization and lookup operations.
+- **Storage and memory:** [BookKeeper batch reads](https://bookkeeper.apache.org/bps/BP-62-new-API-for-batched-reads/) fetch multiple entries per request when draining backlogs of small entries, cache-owned copies and Netty's adaptive allocator improve buffer use, and deferred metadata parsing reduces work when publishing.
+- **Acknowledgments and client scheduling:** compact bitmaps, reused acknowledgment data, and coalesced listener notifications reduce allocation and scheduling overhead; the client-side changes take effect with the 5.0 client library.
 
-- **Publishing and dispatch:** batched handovers reduce executor contention, independent producers avoid a topic-wide deduplication lock, and Shared and Key_Shared dispatch use fewer synchronization and lookup operations.
-- **Storage and memory:** BookKeeper batch reads fetch multiple entries per request using [BP-62 New API for batched reads](https://bookkeeper.apache.org/bps/BP-62-new-API-for-batched-reads/). Cache-owned copies and the [Netty adaptive allocator](https://netty.io/wiki/analyzing-memory-allocator-behavior.html) improve buffer use for small entries. Deferred metadata parsing reduces work on the publishing path, and tiered-storage reads reuse discovered entry offsets.
-- **Acknowledgments and client scheduling:** compact bitmaps, reused acknowledgment data, fewer temporary objects, and coalesced listener notifications reduce allocation and scheduling overhead.
+The [broker performance guide](performance-broker.md) covers the related settings and how to tune them. The [configuration comparison](administration-upgrade-to-5.0.x-configuration.md) helps operators review changed defaults against their own workloads.
 
-The [broker performance guide](performance-broker.md) explains the improvements and tuning options. The [configuration comparison](administration-upgrade-to-5.0.x-configuration.md) helps operators review changed defaults against their own workloads.
+### Seek by timestamp on offloaded topics with fewer object-store requests {#seek-by-timestamp-in-offloaded-topics}
+
+Seeking a topic in [tiered storage](tiered-storage-overview.md) to a timestamp previously meant scanning offloaded data blocks from their start, one ranged read at a time. Pulsar 5.0 remembers the entry offsets it discovers and uses the indexed block starts. Compared with 4.0.13 and 4.2.4, a cold search in the benchmark sent about **90% fewer requests** to the object store (44 ranged reads instead of 428) and a nearby follow-up search about 96% fewer, which also means less data downloade [...]
 
 ### More reliable delivery and recovery {#more-reliable-delivery-and-recovery}
 
@@ -162,7 +146,7 @@ Reliability improvements strengthen the features existing applications use every
 - **Delayed delivery** fixes preserve message indexes through snapshot trimming and tracker recovery, and prevent premature replay.
 - **Acknowledgments and transactions** retain batch acknowledgment state and cursor properties during recovery, prevent already acknowledged messages from reaching dead-letter topics, and keep transactional and non-transactional messages in separate batches.
 
-Assignment and ownership cleanup fixes also improve recovery in the extensible load manager.
+Assignment and ownership cleanup fixes also improve recovery in the extensible load manager. Most of these fixes are also in the 4.0.14 and 4.2.5 maintenance releases.
 
 ## New capabilities {#new-capabilities}
 
@@ -172,23 +156,25 @@ Assignment and ownership cleanup fixes also improve recovery in the extensible l
 
 ### A Java client API built around how you consume {#v5-java-client}
 
-The [v5 Java client API](pathname:///docs/client-libraries/java-v5) gives applications three focused consumption models:
+Scalable Topics are used through the new [v5 Java client API](pathname:///docs/client-libraries/java-v5). Over more than a decade, Pulsar's client API grew one feature at a time, accumulating options, overloads, and subtle inconsistencies; the v5 API is a clean-slate redesign that distills the lessons from production use into a focused API.
+
+Consumption is the clearest example. The v4 client offers a single `Consumer` shaped by one of four subscription types (Exclusive, Failover, Shared, and Key_Shared), plus a separate `Reader`, with behavior that shifts as options are combined. The v5 API replaces them with three purpose-built consumers, each exposing only the operations that make sense for it:
 
-- **Stream consumers** for ordered consumption with cumulative acknowledgment.
-- **Queue consumers** for parallel processing with individual acknowledgments and dead-letter handling.
-- **Checkpoint consumers** for applications that manage their own processing position.
+- **Stream consumers** for ordered consumption with cumulative acknowledgment, including key-shared processing across consumers.
+- **Queue consumers** for parallel work-queue processing with individual and negative acknowledgments and dead-letter handling.
+- **Checkpoint consumers** for stream-processing engines such as Flink and Spark that track their own position, with no subscription or acknowledgment.
 
-The API supports Scalable Topics and existing persistent topics. Applications can also [subscribe across a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting topics by properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts efficiently.
+The v5 API also works with existing partitioned and non-partitioned persistent topics, so you can adopt it before converting any topic. Stream and queue consumers can also [subscribe to all scalable topics in a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting them by their properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts.
 
-**One dependency for the v4, v5, and admin clients.** For new applications or dependency updates, `org.apache.pulsar:pulsar-client-v5-all` provides all three through a single unshaded dependency with transitive dependencies. You can adopt it while continuing to use only the v4 API. See [Pulsar Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configuration) for complete Maven and Gradle examples, BOM alignment, and conflict exclusions, and the [API m [...]
+**One dependency for the v4, v5, and admin clients.** `org.apache.pulsar:pulsar-client-v5-all` contains the Java client, with both the v4 and v5 APIs, and the Java admin client. It is unshaded, so you can upgrade third-party dependencies yourself, for example to address CVEs, without waiting for a Pulsar release; import the Pulsar and Netty BOMs to keep their versions aligned, as described in [Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configu [...]
 
 The v5 API requires scalable-topic services to be enabled on the brokers, including for regular topics. The v4 API works whether those services are enabled or disabled, so application migration can follow the cluster upgrade on its own schedule.
 
 ### Oxia for new clusters, continuity for ZooKeeper deployments {#oxia-and-metadata-migration}
 
-[Oxia](https://oxia-db.github.io/) is fully open source under the [Apache-2.0 license](https://github.com/oxia-db/oxia/blob/main/LICENSE) and has been accepted into CNCF at the [Sandbox maturity level](https://www.cncf.io/projects/oxia/). It is the recommended metadata store for new clusters and the supported choice for Scalable Topics in production. Existing ZooKeeper deployments can continue running their workloads: with Scalable Topics disabled, all previously available features remai [...]
+[Oxia](https://oxia-db.github.io/) is fully open source under the [Apache-2.0 license](https://github.com/oxia-db/oxia/blob/main/LICENSE) and has been accepted into CNCF at the [Sandbox maturity level](https://www.cncf.io/projects/oxia/). It is the recommended metadata store for new Pulsar clusters and for Scalable Topics.
 
-When you choose to move to Oxia, the [metadata-store migration framework](administration-metadata-store-migration.md) copies metadata while publishing and consuming continue, with a planned cutover and validation procedure. You can schedule this separately from the software upgrade. ZooKeeper can also be used to test Scalable Topics in Pulsar 5.0.0; some scalable-topic features, including transactions, require Oxia.
+Existing ZooKeeper deployments can keep running unchanged. When you choose to move to Oxia, the [metadata store migration framework](administration-metadata-store-migration.md) ([PIP-454](https://github.com/apache/pulsar/blob/v5.0.0/pip/pip-454.md)) copies metadata while existing producers and consumers keep running; metadata changes such as topic creation and ledger rollovers pause during the copy. A planned cutover and validation procedure completes the move, which you can schedule sep [...]
 
 [Topic policies can now be stored directly in the metadata store](administration-metadata-store.md#store-topic-policies-in-the-metadata-store). Topics whose policies are stored in system topics keep using them, allowing operators to plan that transition separately as well.