auto-docs: Update property docs for tag v25.3.4 #1530
Conversation
📝 WalkthroughWalkthroughThis PR updates Antora configuration and documentation files to reflect new cluster properties and version changes. The antora.yml file is reformatted with updated version tags, date formats, and content converted to folded scalars. A new properties JSON file documents seven new cluster configuration properties for versions up to v25.3.4, including cloud_topics-related epoch and garbage collection settings, fetch_max_read_concurrency, and log compaction controls. The deprecated properties documentation is updated to include log_compaction_disable_tx_batch_removal. The cluster properties reference guide expands with new configuration entries for cloud deployments and tiered storage scenarios. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
modules/reference/partials/properties/cluster-properties.adoc (2)
11152-11188: Deprecated tx-batch-removal flag still reads like an active tuning option
log_compaction_disable_tx_batch_removalis now typed asdeprecated_propertyand wrapped in// tag::deprecated[], but the description still actively instructs users to “set this totrueif you experience stability issues…”.To reduce confusion now that this is deprecated and superseded by
log_compaction_tx_batch_removal_enabled, consider (via the overrides tooling):
- Updating the description to explicitly say it’s deprecated and point readers to
log_compaction_tx_batch_removal_enabled.- Or, if you don’t want additional text on deprecated properties, trimming the descriptive sentence so users are nudged toward the new flag instead.
This would need to be done in the generation source (for example, property-overrides / doc-tools input), not by editing this file directly.
11338-11404: New tx-batch-removal controls are coherent; only a minor consistency thought
log_compaction_pause_use_sliding_windowmetadata changes keep the same semantics (boolean, defaultfalse, tunable, no restart required).- New
log_compaction_tx_batch_removal_enabledis documented clearly (what gets removed, dependence ondelete.retention.msandcleanup.policy), with consistent boolean metadata and defaultfalse.From a reader’s perspective, the relationship between:
- deprecated
log_compaction_disable_tx_batch_removal, and- new
log_compaction_tx_batch_removal_enabledis implicit via the deprecated tag but not spelled out. If you’re willing to touch the generation inputs, adding a short cross-reference in the new property description (“replaces the deprecated
log_compaction_disable_tx_batch_removal”) would make the migration path obvious. Otherwise, this block is technically sound as-is.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (5)
antora.ymldocs-data/redpanda-property-changes-v25.3.1-to-v25.3.4.jsonmodules/reference/attachments/redpanda-properties-v25.3.4.jsonmodules/reference/partials/deprecated/deprecated-properties.adocmodules/reference/partials/properties/cluster-properties.adoc
🧰 Additional context used
🧠 Learnings (13)
📓 Common learnings
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Update `/docs-data/property-overrides.json` to make changes to property documentation - this is the file that drives auto-generation of property reference pages
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Normalize all xref links in property-overrides.json to use full Antora resource IDs after updating
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Always use full Antora resource IDs with module prefixes in xref links within property descriptions (e.g., `reference:properties/cluster-properties.adoc`, never `./cluster-properties.adoc`)
📚 Learning: 2025-07-16T19:33:20.420Z
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
Applied to files:
docs-data/redpanda-property-changes-v25.3.1-to-v25.3.4.jsonmodules/reference/partials/properties/cluster-properties.adoc
📚 Learning: 2025-07-14T19:28:43.296Z
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Applied to files:
docs-data/redpanda-property-changes-v25.3.1-to-v25.3.4.jsonantora.yml
📚 Learning: 2025-11-25T09:42:15.235Z
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Never add or update descriptions for properties marked as deprecated - remove any existing override for deprecated properties
Applied to files:
modules/reference/partials/deprecated/deprecated-properties.adocmodules/reference/partials/properties/cluster-properties.adoc
📚 Learning: 2025-12-12T16:18:28.126Z
Learnt from: andrewstucki
Repo: redpanda-data/docs PR: 1514
File: modules/troubleshoot/partials/errors-and-solutions.adoc:618-632
Timestamp: 2025-12-12T16:18:28.126Z
Learning: In Redpanda ShadowLink CRD usage, do not copy CA certificates into pods via kubectl cp because they won't persist across pod restarts. Store CA certs in Kubernetes Secrets and reference them in the ShadowLink's staticConfiguration block (or inline the cert data in that block) to ensure persistence and proper secret management.
Applied to files:
modules/reference/partials/deprecated/deprecated-properties.adocmodules/reference/partials/properties/cluster-properties.adoc
📚 Learning: 2025-05-07T01:06:00.937Z
Learnt from: kbatuigas
Repo: redpanda-data/docs PR: 1113
File: modules/manage/partials/iceberg/use-iceberg-catalogs.adoc:100-107
Timestamp: 2025-05-07T01:06:00.937Z
Learning: In AsciiDoc documentation for Redpanda, the syntax `+` and `--` around content blocks within a `[tabs]` section are valid AsciiDoc formatting elements for tabbed content. The `+` after a tab name (like `rpk::`) indicates that the following block belongs to that tab, and the `--` markers enclose the content for that tab. These are not diff artifacts and should not be removed.
Applied to files:
antora.yml
📚 Learning: 2025-11-25T09:42:15.235Z
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Normalize all xref links in property-overrides.json to use full Antora resource IDs after updating
Applied to files:
antora.yml
📚 Learning: 2025-08-13T16:39:20.038Z
Learnt from: JakeSCahill
Repo: redpanda-data/docs PR: 1304
File: modules/troubleshoot/partials/errors-and-solutions.adoc:44-44
Timestamp: 2025-08-13T16:39:20.038Z
Learning: In AsciiDoc documentation with Antora, explicit anchors like [[anchor-name]] take precedence over automatically generated anchors from headings. When troubleshooting cross-references, check for both explicit anchors and auto-generated ones from heading text (lowercase with spaces replaced by hyphens).
Applied to files:
antora.yml
📚 Learning: 2025-08-19T19:26:57.364Z
Learnt from: paulohtb6
Repo: redpanda-data/docs PR: 1324
File: modules/deploy/partials/high-availability.adoc:537-537
Timestamp: 2025-08-19T19:26:57.364Z
Learning: In AsciiDoc documentation, page aliases (`:page-aliases:`) should never be removed as they serve as old redirects to maintain backward compatibility when pages are moved or renamed. They preserve SEO and prevent broken links for users.
Applied to files:
antora.yml
📚 Learning: 2025-11-25T09:42:15.235Z
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Use AsciiDoc formatting in property descriptions: `property_name` for property names, `xref:module:path/to/doc.adoc[Link Text]` for cross-references, and `\n\n` for paragraph breaks
Applied to files:
antora.yml
📚 Learning: 2025-11-25T09:42:15.235Z
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to /modules/reference/partials/properties/*.adoc : Never directly edit files in `/modules/reference/partials/properties/` - they are auto-generated and will be overwritten
Applied to files:
antora.yml
📚 Learning: 2025-11-25T09:42:15.235Z
Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Always use full Antora resource IDs with module prefixes in xref links within property descriptions (e.g., `reference:properties/cluster-properties.adoc`, never `./cluster-properties.adoc`)
Applied to files:
antora.yml
📚 Learning: 2025-09-03T16:34:58.323Z
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1349
File: modules/manage/pages/cluster-maintenance/manage-throughput.adoc:0-0
Timestamp: 2025-09-03T16:34:58.323Z
Learning: For Redpanda documentation, use absolute URLs (https://docs.redpanda.com/api/...) rather than relative URLs (/api/...) when linking to API documentation. Relative API links break in Netlify previews because Bump only serves from docs.redpanda.com, causing the relative URLs to be appended to the preview URL where Bump doesn't serve content.
Applied to files:
antora.yml
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (10)
antora.yml (3)
14-17: Version tags updated consistently for v25.3.4 release.The version metadata updates look correct:
latest-redpanda-tagupdated tov25.3.4latest-console-tagupdated tov3.3.1latest-release-commitupdated with new commit hashlatest-operator-versionupdated tov2.3.8-24.3.6The
full-versionremaining at25.3.1whilelatest-redpanda-tagisv25.3.4is consistent with known version metadata patterns. Based on learnings, version metadata may intentionally show differences that are resolved during the GA merge process.
29-32: YAML formatting normalized.The changes from quoted to unquoted strings for the supported platform versions are semantically equivalent and improve consistency. The values
9+,20.04 LTS,22.04+remain unchanged.
78-96: Home page content reformatted to folded scalars.The conversion from quoted strings to folded scalar style (
>-) and unquoted scalars maintains the same content while improving YAML readability. No semantic changes to the page content.modules/reference/partials/deprecated/deprecated-properties.adoc (1)
74-75: Deprecated property added correctly.The
log_compaction_disable_tx_batch_removalproperty is:
- Inserted in correct alphabetical order
- Formatted consistently with existing entries
- Aligned with the deprecation noted in the property changes JSON file
docs-data/redpanda-property-changes-v25.3.1-to-v25.3.4.json (3)
1-15: Changelog structure and summary are consistent.The summary counts accurately reflect the detailed entries:
- 7 new properties documented with types, defaults, and descriptions
- 1 deprecated property (
log_compaction_disable_tx_batch_removal)- 3 properties flagged with empty descriptions for future attention
54-68: Property naming pattern follows convention.The deprecation of
log_compaction_disable_tx_batch_removaland introduction oflog_compaction_tx_batch_removal_enabledfollows a common pattern of inverting negative-logic property names to positive-logic (disable_*→*_enabled). The new property defaults tofalse, which maintains backward-compatible behavior.
71-84: Empty descriptions flagged for visibility.The three properties with empty descriptions (
redpanda.cloud_topic.enabled,redpanda.remote.allowgaps,redpanda.virtual.cluster.id) are correctly identified. These appear to be internal/topic-level properties. Consider adding descriptions via the property overrides mechanism if these are user-facing configuration options.modules/reference/partials/properties/cluster-properties.adoc (3)
959-1044: Epoch service properties look structurally consistentBoth
cloud_topics_epoch_service_epoch_increment_intervalandcloud_topics_epoch_service_local_epoch_cache_durationfollow the existing conventions (integer type, standard range, ms defaults with human-readable durations, nullable=no, tunable visibility, restore flags). I don’t see structural or semantic issues here.
1271-1400: Short-term GC properties are well-aligned with existing cloud_topics GC knobsThe three new properties:
cloud_topics_short_term_gc_backoff_intervalcloud_topics_short_term_gc_intervalcloud_topics_short_term_gc_minimum_object_ageall use the standard integer + range + ms defaults pattern, with clear descriptions of “no progress / progress / minimum age” semantics. Flags for restart, visibility, and restore behavior are consistent with nearby GC settings. No issues from a docs-structure or clarity standpoint.
5254-5297:fetch_max_read_concurrencyentry is clear and consistentThe new
fetch_max_read_concurrencyproperty doc:
- Correctly describes behavior (max concurrent partition reads per fetch per shard).
- Uses the usual integer + default + tunable metadata.
- Warns about the downside of increasing the value.
This fits well alongside the other fetch-tuning properties and should be helpful to operators.
|
Marking this as a draft until #1529 is merged. Looks like a property was marked deprecated in 25.3.4. |
|
@paulohtb6 to stop these changes to antora.yml we need to merge redpanda-data/docs-extensions-and-macros#162 |
This PR auto-generates updated Redpanda property documentation for v25.3.4.