docs: add aliases to properties #1284
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis set of documentation updates standardizes and clarifies the naming and referencing of several configuration properties across multiple modules. Key changes include renaming and aliasing of properties related to AWS Glue credentials, log retention, and object storage. Documentation examples and references are updated to use the primary property names, with deprecated or alias names clearly indicated. Several cross-references and inline code snippets are adjusted for consistency. No code logic or functional changes are involved; all updates are limited to documentation content and property references. Sequence Diagram(s)Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![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 (3)
modules/manage/pages/iceberg/iceberg-topics-aws-glue.adoc (1)
84-90: Minor wording mismatch after alias renameThe paragraph intro still says “properties named
iceberg_rest_catalog_aws_*”, but the credentials‐source key is nowiceberg_rest_catalog_credentials_source(without_aws_).
Consider adjusting the sentence to avoid confusion, e.g.:… there are equivalent credential configuration properties named `iceberg_rest_catalog_*`, such as …or list the explicit keys.
modules/upgrade/pages/deprecated/index.adoc (1)
45-48: Consider retaining the cross-referenceReplacing the
xref:macro with inline code removes the handy link to the property definition.
If the alias anchor#delete_retention_msis still generated, keeping thexref:would let readers jump straight to the details.modules/reference/pages/properties/cluster-properties.adoc (1)
3859-3860: Alias fordelete_retention_ms– double-check deprecation wordingAdding
delete_retention_msas an alias is correct. However, many HOW-TO pages still instruct users to setdelete_retention_ms. Consider inserting a short deprecation sentence so that readers learn the preferred name (log_retention_ms).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
modules/manage/pages/iceberg/iceberg-topics-aws-glue.adoc(1 hunks)modules/manage/partials/audit-logging.adoc(1 hunks)modules/manage/partials/tiered-storage.adoc(1 hunks)modules/reference/pages/properties/cluster-properties.adoc(7 hunks)modules/reference/pages/properties/object-storage-properties.adoc(2 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc(1 hunks)modules/troubleshoot/partials/debug-bundle/inspect.adoc(2 hunks)modules/upgrade/pages/deprecated/index.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Feediver1
PR: redpanda-data/docs#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.
📚 Learning: in the redpanda documentation, topic property cross-references like <> and <<...
Learnt from: Feediver1
PR: redpanda-data/docs#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:
modules/manage/partials/audit-logging.adocmodules/upgrade/pages/deprecated/index.adocmodules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adocmodules/troubleshoot/partials/debug-bundle/inspect.adocmodules/reference/pages/properties/object-storage-properties.adocmodules/manage/partials/tiered-storage.adocmodules/reference/pages/properties/cluster-properties.adoc
📚 Learning: in asciidoc documentation for redpanda, the syntax `+` and `--` around content blocks within a `[tab...
Learnt from: kbatuigas
PR: redpanda-data/docs#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:
modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc
⏰ 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 (12)
modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc (1)
60-69: Example updated to canonical property – nice touchSwitching the example from
delete_retention_msto the canonicallog_retention_mskeeps the docs consistent with the new alias strategy. The negative-value gotcha is still demonstrated correctly, so no further change is required.modules/manage/partials/audit-logging.adoc (1)
360-366: Reference updated to canonical property – looks goodThe link now targets
log_retention_ms, aligning the audit-logging guidance with the new alias scheme.modules/reference/pages/properties/object-storage-properties.adoc (2)
867-873: Alias line added – formatting and placement correct
*Aliases:* cloud_storage_graceful_transfer_timeoutfollows the established bullet style and renders correctly.
1221-1224: Alias added for reader limit property – LGTMConsistent alias entry for
cloud_storage_max_readers_per_shardaids discoverability without impacting formatting.modules/manage/partials/tiered-storage.adoc (1)
1013-1016: Verify thatlog_retention_msanchor exists to avoid a broken config_ref linkYou switched the default-retention reference from
delete_retention_mstolog_retention_ms.
Given past incidents (see learning about missing anchors), please double-check that[[logretentionms]](or the macro-generated equivalent) is present incluster-properties.adoc; otherwise this cross-reference will break the build.modules/troubleshoot/partials/debug-bundle/inspect.adoc (2)
96-102: Property name changed – confirm the alias exists in Redpanda config
transaction_coordinator_log_retention_msreplaces the former*_delete_retention_ms.
Make sure this alias was actually added to the product (and documented incluster-properties.adoc). If the backend still expects the old key, copy-pasting this example will confuse users.
380-388: Keep example JSON aligned with broker-level synonymsThe synonym array now lists
"log_retention_ms", matching the key that replacesdelete_retention_ms. Perfect—just ensure other examples (audit-logging, rpk-cluster, etc.) were updated the same way so we don’t surface two different names in the docs.modules/reference/pages/properties/cluster-properties.adoc (5)
841-842: Check that the docs build picks up the new alias anchor
*Aliases:* wasm_per_core_memory_reservationlooks fine, but the AsciiDoc toolchain must actually generate an anchor so that<<wasm_per_core_memory_reservation>>links resolve. Make sure the docs-build task renders the alias in the property index and that no unresolved-xref warnings appear.
866-867: Verify alias resolution forwasm_per_function_memory_limitSame concern as above – please run the link-check to confirm that any existing
<<wasm_per_function_memory_limit>>references resolve after the build.
2271-2272: Alias adds backwards-compatibility – confirm old cross-refs updatedGood call adding
iceberg_rest_catalog_aws_credentials_sourceas an alias. Double-check that every doc that previously linked to the old name now links only through<<iceberg_rest_catalog_credentials_source>>; otherwise you’ll have two competing canonical anchors.
2613-2614: Prefix/warehouse rename – guard against broken examplesThe alias covers the rename, but examples under
icebergguides were updated in a separate file. Please grep foriceberg_rest_catalog_prefixin the repo and ensure every occurrence is now either an xref to this property or part of an explicit “deprecated” note.
5684-5685: Schema-registry alias OK – check for duplicate property headingsYou removed the separate
schema_registry_normalize_on_startupsection and substituted an alias. Ensure there is no leftover orphan=== schema_registry_normalize_on_startupheading elsewhere in this file; otherwise the AsciiDoc ID clash will break navigation.
paulohtb6
force-pushed
the
propery-aliases
branch
from
d6942bb to
7fc53e0
Compare
Description
Content change related to redpanda-data/docs-extensions-and-macros#123
Resolves https://redpandadata.atlassian.net/browse/DOC-415
Review deadline:
Page previews
Checks