add note about changes

change admonition

Author: paulohtb6

modules/develop/pages/config-topics.adoc

@@ -98,6 +98,11 @@ The cleanup policy determines how to clean up the partition log files when they
 
 Unlike compacted topics, which keep only the most recent message for a given key, topics configured with a `delete` cleanup policy provide a running history of all changes for those topics.
 
+[NOTE]
+====
+include::shared:partial$tristate-behavior-change-25-3.adoc[]
+====
+
 include::develop:partial$topic-properties-warning.adoc[]
 
 For example, to change a topic's policy to `compact`, run:

modules/get-started/pages/release-notes/redpanda.adoc

@@ -144,6 +144,23 @@ The following configuration properties have new default values in v25.3:
 * xref:reference:properties/cluster-properties.adoc#partition_autobalancing_mode[`partition_autobalancing_mode`]: Changed from `node_add` to `continuous` (Enterprise license required).
 * xref:reference:properties/cluster-properties.adoc#iceberg_throttle_backlog_size_ratio[`iceberg_throttle_backlog_size_ratio`]: Changed from `0.3` to `null`.
 
+[[behavior-changes]]
+=== Behavior changes
+
+The following topic properties now support enhanced tristate behavior:
+
+* xref:reference:properties/topic-properties.adoc#segmentms[`segment.ms`]
+* xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]
+* xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]
+* xref:reference:properties/topic-properties.adoc#retentionlocaltargetbytes[`retention.local.target.bytes`]
+* xref:reference:properties/topic-properties.adoc#retentionlocaltargetms[`retention.local.target.ms`]
+* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetbytes[`initial.retention.local.target.bytes`]
+* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetms[`initial.retention.local.target.ms`]
+* xref:reference:properties/topic-properties.adoc#deleteretentionms[`delete.retention.ms`]
+* xref:reference:properties/topic-properties.adoc#mincleanabledirtyratio[`min.cleanable.dirty.ratio`]
+
+Previously, these properties treated zero and negative values the same way. Now they support three distinct states: positive values set specific limits, zero provides immediate eligibility for cleanup/compaction, and negative values inherit cluster defaults. Review your topic configurations if you currently use zero values for these properties.
+
 === Deprecations
 
 The following configuration properties have been deprecated in v25.3 and will be removed in a future release:

modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc

@@ -53,6 +53,11 @@ NOTE: For the full list of properties, see xref:reference:topic-properties.adoc[
 
 endif::[]
 
+[IMPORTANT]
+====
+include::shared:partial$tristate-behavior-change-25-3.adoc[]
+====
+
 == Examples
 
 === Create a topic

modules/shared/partials/tristate-behavior-change-25-3.adoc

@@ -0,0 +1 @@
+Starting in Redpanda v25.3, several topic properties support enhanced tristate behavior. Properties like `retention.ms`, `retention.bytes`, `segment.ms`, and others now distinguish between zero values (immediate eligibility for cleanup/compaction) and negative values (inherit cluster defaults). Previously, zero and negative values were treated the same way. For the complete list of affected properties and detailed information, see xref:25.3@get-started:release-notes/redpanda.adoc#behavior-changes[Redpanda v25.3 behavior changes]. Review your topic configurations if you currently use zero values for these properties.

modules/upgrade/partials/incompat-changes.adoc

@@ -8,6 +8,12 @@ include::upgrade:partial$iceberg-breaking-changes.adoc[]
 --
 ** Schema Registry no longer allows specifying a schema ID and version when registering a schema in read-write mode. You must use import mode to register a schema with a specific ID and version. See xref:manage:schema-reg/schema-reg-api.adoc#set-schema-registry-mode[Use the Schema Registry API] for more information.
 
+** {empty}
++
+--
+include::shared:partial$tristate-behavior-change-25-3.adoc[]
+--
+
 * {empty}
 +
 --