update descriptions

Author: paulohtb6

docs-data/property-overrides.json

@@ -670,7 +670,7 @@
       "config_scope": "cluster"
     },
     "delete.retention.ms": {
-      "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <<redpandaremoteread,`redpanda.remote.read`>> or <<redpandaremotewrite,`redpanda.remote.write`>> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`].",
+      "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <<redpandaremoteread,`redpanda.remote.read`>> or <<redpandaremotewrite,`redpanda.remote.write`>> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: Disables tombstone removal entirely for this topic.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`]",
         "xref:manage:cluster-maintenance/compaction-settings.adoc#tombstone-record-removal[Tombstone record removal]"
@@ -1319,7 +1319,7 @@
       "config_scope": "cluster"
     },
     "min.cleanable.dirty.ratio": {
-      "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`].",
+      "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: This property is not considered when deciding if a log is eligible for compaction.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`]"
       ],
@@ -1688,7 +1688,7 @@
       "config_scope": "topic"
     },
     "retention.bytes": {
-      "description": "A size-based retention limit that configures the maximum size that a topic partition can grow before becoming eligible for cleanup.\n\nIf `retention.bytes` is set to a positive value, it overrides the cluster property xref:cluster-properties.adoc#retention_bytes[`retention_bytes`] for the topic, and the total retained size for the topic is `retention.bytes` multiplied by the number of partitions for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, cleanup occurs when either limit is reached.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup.\n* 0: Partitions are immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`].",
+      "description": "A size-based retention limit that configures the maximum size that a topic partition can grow before becoming eligible for cleanup.\n\nIf `retention.bytes` is set to a positive value, it overrides the cluster property xref:cluster-properties.adoc#retention_bytes[`retention_bytes`] for the topic, and the total retained size for the topic is `retention.bytes` multiplied by the number of partitions for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, cleanup occurs when either limit is reached.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup.\n* 0: Partitions are immediately eligible for cleanup.\n* Negative value: Disables size-based retention for this topic.",
       "related_topics": [
         "xref:cluster-properties.adoc#retention_bytes[`retention_bytes`]",
         "xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`]",
@@ -1697,15 +1697,15 @@
       "config_scope": "topic"
     },
     "retention.local.target.bytes": {
-      "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <<retentionbytes, `retention.bytes`>> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`].",
+      "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <<retentionbytes, `retention.bytes`>> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables size-based local retention override for this topic.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]",
         "xref:manage:tiered-storage.adoc[Tiered Storage]"
       ],
       "config_scope": "topic"
     },
     "retention.local.target.ms": {
-      "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`].",
+      "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to <<retentionms, `retention.ms`>> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables time-based local retention override for this topic.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#retention_local_target_ms[`retention_local_target_ms`]",
         "xref:manage:tiered-storage.adoc[Tiered Storage]",
@@ -1714,7 +1714,7 @@
       "config_scope": "topic"
     },
     "retention.ms": {
-      "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`].",
+      "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: Disables time-based retention for this topic.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`]",
         "xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention]"
@@ -1926,7 +1926,7 @@
       "config_scope": "topic"
     },
     "segment.ms": {
-      "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`].",
+      "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nFor topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Disables time-based segment rolling for this topic.",
       "related_topics": [
         "xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`]",
         "xref:reference:properties/cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`]",

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

@@ -159,7 +159,7 @@ The following topic properties now support enhanced tristate behavior:
 * 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.
+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 disable the feature entirely. Review your topic configurations if you currently use zero values for these properties.
 
 === Deprecations
 

modules/reference/partials/properties/topic-properties.adoc

@@ -325,7 +325,7 @@ This property supports three states:
 
 * Positive value: Sets the milliseconds to retain tombstone records before removal.
 * 0: Tombstone records are immediately eligible for removal.
-* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`].
+* Negative value: Disables tombstone removal entirely for this topic.
 
 [cols="1s,2a"]
 |===
@@ -847,7 +847,7 @@ This property supports three states:
 
 * Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.
 * 0: Compaction is always eligible regardless of dirty ratio.
-* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`].
+* Negative value: This property is not considered when deciding if a log is eligible for compaction.
 
 [cols="1s,2a"]
 |===
@@ -1726,7 +1726,7 @@ This property supports three states:
 
 * Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup.
 * 0: Partitions are immediately eligible for cleanup.
-* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`].
+* Negative value: Disables size-based retention for this topic.
 
 [cols="1s,2a"]
 |===
@@ -1781,7 +1781,7 @@ This property supports three states:
 
 * Positive value: Sets the maximum bytes per partition in local storage before cleanup.
 * 0: Data in local storage is immediately eligible for cleanup.
-* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`].
+* Negative value: Disables size-based local retention override for this topic.
 
 [cols="1s,2a"]
 |===
@@ -1828,13 +1828,13 @@ endif::[]
 // tag::category-tiered-storage[]
 === retention.local.target.ms
 
-A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup.
+A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to <<retentionms, `retention.ms`>> without Tiered Storage.
 
 This property supports three states:
 
 * Positive value: Sets the maximum milliseconds to retain data in local storage.
 * 0: Data in local storage is immediately eligible for cleanup.
-* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`].
+* Negative value: Disables time-based local retention override for this topic.
 
 [cols="1s,2a"]
 |===
@@ -1893,7 +1893,7 @@ This property supports three states:
 
 * Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.
 * 0: Data is immediately eligible for cleanup.
-* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`].
+* Negative value: Disables time-based retention for this topic.
 
 [cols="1s,2a"]
 |===
@@ -1999,11 +1999,13 @@ The maximum duration that a log segment of a topic is active (open for writes an
 
 If set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.
 
+For topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`.
+
 This property supports three states:
 
 * Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.
 * 0: Segments are immediately eligible for closure.
-* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`].
+* Negative value: Disables time-based segment rolling for this topic.
 
 [cols="1s,2a"]
 |===