docs: list configuration changes in the 1.x to 2.x migration guide

docs/src/main/paradox/additional/rolling-updates.md

@@ -159,8 +159,11 @@ The magic header has evolved across versions:
  * Pekko 2.x (and above) sends `"PEKK"` by default but accepts both `"PEKK"` and `"AKKA"`.
 
 Because Pekko 1.7.x+ and 2.x accept both values by default, rolling upgrades between these versions
-do not require changing the `tcp-magic` configuration. Upgrading from Pekko 1.6.x or earlier to 2.x
-directly is also supported since the 2.x default accepts `"AKKA"`.
+do not require changing the `tcp-magic` configuration.
+
+Pekko 1.6.x and earlier reject the `"PEKK"` header that Pekko 2.x sends by default. Upgrade to Pekko 1.7.x
+first, or, if you upgrade from Pekko 1.6.x or earlier directly to 2.x, set
+`pekko.remote.artery.advanced.tcp-magic = ["AKKA", "PEKK"]` on the 2.x nodes until all nodes run 2.x.
 
 If you remove `"AKKA"` from the array, nodes running older versions will be unable to connect.
 

docs/src/main/paradox/migration/migration-guide-1.x-2.x.md

@@ -48,3 +48,168 @@ Java users should match on `ReceiveTimeout.class` instead.
 (`pekko.remote.artery.advanced.tcp-magic`). See
 @ref:[Changing TCP magic header](../additional/rolling-updates.md#changing-tcp-magic-header) for what this means for
 rolling updates. ([PR3425](https://github.com/apache/pekko/pull/3425))
+
+## Configuration Changes in Pekko 2.x
+
+The `reference.conf` defaults have changed in a number of places. If you override any of the settings
+below in your `application.conf`, or rely on their Pekko 1.x defaults, review this list.
+
+Some of these settings were also backported to Pekko 1.x releases. Those entries note the Pekko version
+in which the setting first appeared, so if you are already on that version or later you may have seen
+them before.
+
+### Changed default values
+
+* `pekko.actor.default-dispatcher.fork-join-executor.minimum-runnable` changed from `1` to `-1`.
+The setting first appeared in Pekko 1.7.0, with a default of `1`.
+The value `-1` selects a JDK-aware default: on JDK 25 and later the effective value is
+`min(8, max(1, parallelism / 2))`, and on earlier JDKs it is `1`, so the behavior only changes on
+JDK 25 and later. Set it explicitly to `1` to restore the Pekko 1.x behavior on all JDKs.
+The internal dispatcher (`pekko.actor.internal-dispatcher.fork-join-executor`) uses the same new default.
+([PR2890](https://github.com/apache/pekko/pull/2890))
+* `pekko.remote.artery.propagate-harmless-quarantine-events` changed from `on` to `off`, so harmless
+quarantine events are no longer propagated by default. ([PR2430](https://github.com/apache/pekko/pull/2430))
+* `pekko.remote.artery.advanced.tcp-magic` changed from `["AKKA", "PEKK"]` to `["PEKK", "AKKA"]`
+(see the TCP magic header note above). The setting first appeared in Pekko 1.7.0, with a default of
+`["AKKA", "PEKK"]`. ([PR3425](https://github.com/apache/pekko/pull/3425))
+* Artery compression heavy hitter detection is controlled by the new setting
+`pekko.remote.artery.advanced.compression.frequency-sketch-implementation`, which defaults to
+`"fast-frequency-sketch"` (a smaller, aging sketch). Set it to `"count-min-sketch"` to restore the
+Pekko 1.x implementation. ([PR3023](https://github.com/apache/pekko/pull/3023))
+* Persistence plugins no longer use the dedicated `pekko.persistence.dispatchers` by default. The
+`plugin-dispatcher` and `replay-dispatcher` settings in the journal and snapshot-store plugin
+fallbacks changed from `pekko.persistence.dispatchers.default-plugin-dispatcher` /
+`pekko.persistence.dispatchers.default-replay-dispatcher` to `pekko.actor.default-dispatcher`.
+The `pekko.persistence.dispatchers` definitions are deprecated; plugins that need a custom
+dispatcher should define their own. ([PR2482](https://github.com/apache/pekko/pull/2482))
+* `pekko.serialization.jackson.read.max-document-length` and
+`pekko.serialization.jackson.read.max-token-count` changed from `-1` to `unlimited`, a value they now
+accept. Negative numbers such as `-1` still mean unlimited, so the effective limits are unchanged and
+existing overrides keep working. The same applies under `pekko.serialization.jackson3`.
+([PR3522](https://github.com/apache/pekko/pull/3522))
+
+### Changed behavior
+
+* `pekko.remote.artery.ssl.rotating-keys-engine.ca-cert-file` may now bundle more than one
+certificate (for example a root CA and its intermediates, or several roots while a CA is being
+rotated); all of them are trusted. Pekko 1.x only loaded the first certificate in the file. The
+setting and its default are unchanged. If your CA file contains certificates you do not intend to
+trust, remove them before upgrading. ([PR3528](https://github.com/apache/pekko/pull/3528))
+
+### Removed configuration
+
+* `pekko.actor.typed.timeout` was removed along with the deprecated `TypedActor` API.
+([PR1969](https://github.com/apache/pekko/pull/1969))
+* `pekko.cluster.sharding.passivate-idle-entity-after` was removed; use
+`pekko.cluster.sharding.passivation.default-idle-strategy.idle-entity.timeout` instead.
+([PR3026](https://github.com/apache/pekko/pull/3026))
+* The `pekko.ssl-config` and top-level `ssl-config` sections were removed along with the
+`ssl-config` library dependency. ([PR2127](https://github.com/apache/pekko/pull/2127))
+
+### New configuration
+
+The full `reference.conf` for each module, with descriptions of every setting, is listed in the
+@ref:[default configuration reference](../general/configuration-reference.md).
+
+@ref:[pekko-actor](../general/configuration-reference.md#config-pekko-actor):
+
+* `pekko.actor.default-dispatcher.fork-join-executor.virtual-thread-start-number`,
+`pekko.actor.default-dispatcher.thread-pool-executor.virtual-thread-start-number` and
+`pekko.actor.default-dispatcher.virtual-thread-executor.virtual-thread-start-number` control the
+starting id for virtual threads created by a dispatcher. ([PR2242](https://github.com/apache/pekko/pull/2242))
+* `pekko.actor.default-dispatcher.thread-pool-executor.virtualize` allows a thread-pool-executor
+based dispatcher to run on virtual threads (JDK 21+). The same settings were added to
+`pekko.actor.default-blocking-io-dispatcher.thread-pool-executor`.
+([PR2169](https://github.com/apache/pekko/pull/2169))
+* `pekko.scheduled-clock-interval` controls how frequently the clock used by recency-based
+passivation strategies is updated. ([PR2766](https://github.com/apache/pekko/pull/2766))
+* The async DNS resolver actors now run on the DNS dispatcher via the new deployment entries
+`pekko.actor.deployment."/IO-DNS/async-dns/*"` and (in
+@ref:[pekko-discovery](../general/configuration-reference.md#config-pekko-discovery))
+`pekko.actor.deployment."/SD-DNS/async-dns/*"`. ([PR2895](https://github.com/apache/pekko/pull/2895))
+* `pekko.actor.serialization-max-nesting-depth` (default `32`) bounds the nesting depth when a
+serialized payload encloses another serialized payload. First appeared in Pekko 1.7.1.
+([PR3500](https://github.com/apache/pekko/pull/3500))
+* `pekko.serialization.max-decompressed-size` (default `unlimited`) bounds the size a gzipped payload
+may expand to when the cluster, cluster-metrics, cluster-sharding, cluster-tools and distributed-data
+serializers decompress it. First appeared in Pekko 1.7.1.
+([PR3502](https://github.com/apache/pekko/pull/3502))
+
+@ref:[pekko-cluster-sharding-typed](../general/configuration-reference.md#config-cluster-sharding-typed),
+@ref:[pekko-cluster-sharding](../general/configuration-reference.md#config-cluster-sharding) and
+@ref:[pekko-distributed-data](../general/configuration-reference.md#config-distributed-data):
+
+* `pekko.cluster.sharded-daemon-process.keep-alive-from-number-of-nodes` and
+`pekko.cluster.sharded-daemon-process.keep-alive-throttle-interval` tune keep-alive pinging, which
+is now performed from a limited number of nodes instead of every node.
+([PR2734](https://github.com/apache/pekko/pull/2734))
+* `pekko.cluster.sharding.healthcheck.disabled-after` disables the sharding health check after the
+configured duration post member-up. ([PR2785](https://github.com/apache/pekko/pull/2785))
+* `pekko.cluster.distributed-data.expire-keys-after-inactivity` configures automatic expiry of
+inactive Distributed Data keys. ([PR2733](https://github.com/apache/pekko/pull/2733))
+
+@ref:[pekko-persistence](../general/configuration-reference.md#config-pekko-persistence),
+@ref:[pekko-persistence-typed](../general/configuration-reference.md#config-pekko-persistence-typed) and
+@ref:[pekko-persistence-query](../general/configuration-reference.md#config-pekko-persistence-query):
+
+* `pekko.persistence.query.events-by-slice-firehose` is a new section configuring the
+events-by-slice firehose query that fans out one shared journal query to many consumers.
+([PR3277](https://github.com/apache/pekko/pull/3277))
+* `pekko.persistence.typed.event-writer.max-batch-size` and
+`pekko.persistence.typed.event-writer.ask-timeout` configure the event writer.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+* `replay-batch-size` in the journal plugin fallback bounds the number of replayed events queued in
+a recovering persistent actor's mailbox. ([PR3325](https://github.com/apache/pekko/pull/3325))
+* `only-one-snapshot` in the snapshot-store plugin fallback enables retention optimizations for
+snapshot stores that only keep the latest snapshot. ([PR2767](https://github.com/apache/pekko/pull/2767))
+* `pekko.persistence.journal.inmem.delay-writes` can add an artificial write delay in tests.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+
+@ref:[pekko-remote classic](../general/configuration-reference.md#config-pekko-remote) and
+@ref:[pekko-remote Artery](../general/configuration-reference.md#config-pekko-remote-artery):
+
+* `pekko.remote.classic.passive-connection-buffer-size` bounds message buffering during a passive
+connection handoff. ([PR3361](https://github.com/apache/pekko/pull/3361))
+* `pekko.remote.classic.netty.ssl.security.hostname-verification` enables TLS hostname verification
+for classic remoting. ([PR3164](https://github.com/apache/pekko/pull/3164))
+* `pekko.remote.artery.advanced.shutdown-streams-timeout` bounds the graceful drain of Artery
+streams during shutdown. ([PR3317](https://github.com/apache/pekko/pull/3317))
+* `pekko.remote.artery.ssl.rotating-keys-engine.keystore-password` sets the password for the
+in-memory keystore used to wrap PEM-loaded keys; override it in production.
+([PR3397](https://github.com/apache/pekko/pull/3397))
+
+@ref:[pekko-serialization-jackson](../serialization-jackson.md):
+
+* `pekko.serialization.jackson.compression.max-decompressed-size` (default `unlimited`) bounds the size
+of a payload after decompression. The same setting exists under `pekko.serialization.jackson3`.
+First appeared in Pekko 1.7.1. ([PR3491](https://github.com/apache/pekko/pull/3491),
+[PR3515](https://github.com/apache/pekko/pull/3515))
+* The new `pekko-serialization-jackson3` module (based on Jackson 3) is configured under
+`pekko.serialization.jackson3`, mirroring the `pekko.serialization.jackson` settings.
+([PR2348](https://github.com/apache/pekko/pull/2348))
+
+@ref:[pekko-stream](../general/configuration-reference.md#config-pekko-stream):
+
+* `pekko.stream.materializer.stage-errors-default-log-level` controls the log level used for
+stream stage errors. ([PR2805](https://github.com/apache/pekko/pull/2805))
+* `pekko.stream.materializer.stage-actor-drain-batch` bounds the number of stage-actor messages
+drained per envelope for lazily materialized stage actors. ([PR3035](https://github.com/apache/pekko/pull/3035))
+* `pekko.stream.materializer.tls.engine` selects the stream TLS engine implementation
+(`"legacy-actor"` or the opt-in `"graph-stage"`). ([PR2878](https://github.com/apache/pekko/pull/2878))
+
+### Serialization bindings
+
+These serialization changes matter if you do a rolling update from Pekko 1.x to 2.x, or need to roll
+back:
+
+* `org.apache.pekko.util.ByteString$ByteString2`, a new `ByteString` implementation, is bound to the
+existing `primitive-bytestring` serializer. That serializer writes no manifest, so Pekko 1.x nodes read
+these messages as an ordinary `ByteString`. ([PR2924](https://github.com/apache/pekko/pull/2924))
+* The `typed-sharding` serializer is now bound to the internal `ClusterShardingTypedSerializable` marker
+instead of `ShardingEnvelope`. `ShardingEnvelope` is serialized as before, but the serializer also
+handles new Sharded Daemon Process messages (its state, and the commands for getting and changing the
+number of processes) that Pekko 1.x nodes cannot deserialize. ([PR2755](https://github.com/apache/pekko/pull/2755))
+* The new `FilteredPayload` placeholder, which is stored in the journal in place of a filtered event
+(for example with events-by-slice queries and projections), has a new serializer with identifier `34`.
+Pekko 1.x cannot deserialize it, so do not run Pekko 1.x against a journal once such events have been
+written. ([PR3275](https://github.com/apache/pekko/pull/3275))

docs/src/main/paradox/project/rolling-update.md

@@ -13,4 +13,19 @@ update completely before starting next update.
 @ref:[Rolling update from classic remoting to Artery](../additional/rolling-updates.md#migrating-from-classic-remoting-to-artery) is not supported since the protocol
 is completely different. It will require a full cluster shutdown and new startup.
 
-@@@
+@@@
+
+## Upgrading from Pekko 1.x to 2.x
+
+Pekko 2.x is not binary compatible with Pekko 1.x, so all the Pekko modules (and any libraries built on
+Pekko 1.x) must be upgraded together. Read the
+@ref:[migration guide](../migration/migration-guide-1.x-2.x.md) before planning a rolling update, in
+particular the breaking changes and the configuration changes, and check how they affect the messages
+exchanged between nodes, your persisted data and your configuration.
+
+For a rolling update of a cluster from Pekko 1.x to 2.x:
+
+* First upgrade the whole cluster to the latest Pekko 1.7.x release. Pekko 2.x sends a different Artery
+  TCP magic header by default, which Pekko 1.6.x and earlier reject, see
+  @ref:[Changing TCP magic header](../additional/rolling-updates.md#changing-tcp-magic-header).
+* Then roll out Pekko 2.x as a separate update.