Use Antora config to determine current version #145
Conversation
✅ Deploy Preview for docs-extensions-and-macros 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 pull request consolidates utility functions and enhances the documentation build automation. The Sequence DiagramsequenceDiagram
participant CLI as bin/doc-tools.js
participant Antora as Antora Config
participant Make as make(tag)
participant Report as Property Report
CLI->>Antora: Read latest-redpanda-tag (if --diff not provided)
Antora-->>CLI: oldTag or undefined
alt oldTag exists and differs from newTag
CLI->>Make: make(oldTag, ...)
Make-->>CLI: oldTag built
CLI->>Make: make(newTag, ...)
Make-->>CLI: newTag built
CLI->>Report: generatePropertyComparisonReport(oldTag, newTag)
Report-->>CLI: Comparison complete
CLI->>Antora: Update latest-redpanda-tag to newTag
else oldTag == newTag or oldTag missing
CLI->>Make: make(newTag, ...)
Make-->>CLI: newTag built
CLI->>CLI: Skip diff generation
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20–25 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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. Comment |
![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 (1)
bin/doc-tools.js (1)
1091-1133: Consider clarifying thetempDirparameter usage.The
make()function is well-structured, but thetempDirparameter is always passed asnullin the current implementation (lines 1145, 1147). Since both builds write to the sameoutputDirwith tag-prefixed filenames (which prevents collisions), this works correctly.However, the parameter suggests a use case (writing to temporary directories) that isn't currently utilized. Consider either:
- Documenting why
tempDiris designed this way (for future extensibility)- Or simplifying by removing the parameter if it's not needed
If keeping the parameter for future use, add a JSDoc comment explaining when
tempDirshould be used versusnull:+/** + * Build property documentation for a specific tag. + * @param {string} tag - Git tag to extract from + * @param {string} overrides - Path to overrides file + * @param {object} templates - Template file paths + * @param {string} outDir - Output directory for final files + * @param {string|null} tempDir - Optional temp directory for intermediate builds (null to use outDir) + */ const make = (tag, overrides, templates = {}, outDir = 'modules/reference/', tempDir = null) => {
📜 Review details
Configuration used: CodeRabbit 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 ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (6)
bin/doc-tools.js(3 hunks)cli-utils/antora-utils.js(5 hunks)cli-utils/beta-from-antora.js(0 hunks)package.json(1 hunks)tools/get-console-version.js(1 hunks)tools/get-redpanda-version.js(1 hunks)
💤 Files with no reviewable changes (1)
- cli-utils/beta-from-antora.js
🧰 Additional context used
🧬 Code graph analysis (2)
tools/get-console-version.js (2)
bin/doc-tools.js (11)
require(3-3)require(5-5)require(8-8)require(10-10)require(11-11)require(13-13)require(14-17)require(851-851)require(1363-1363)require(1575-1575)require(1582-1582)tools/get-redpanda-version.js (1)
require(4-4)
tools/get-redpanda-version.js (2)
bin/doc-tools.js (11)
require(3-3)require(5-5)require(8-8)require(10-10)require(11-11)require(13-13)require(14-17)require(851-851)require(1363-1363)require(1575-1575)require(1582-1582)tools/get-console-version.js (1)
require(7-7)
⏰ 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 - docs-extensions-and-macros
- GitHub Check: Header rules - docs-extensions-and-macros
- GitHub Check: Pages changed - docs-extensions-and-macros
🔇 Additional comments (11)
package.json (1)
3-3: LGTM!The version bump from 4.10.6 to 4.10.7 is appropriate for the feature enhancements introduced in this PR.
cli-utils/antora-utils.js (4)
13-25: LGTM: Clean support for both .yml and .yaml extensions.The implementation correctly prioritizes
antora.ymloverantora.yamland gracefully handles the case where neither file exists.
85-137: LGTM: Consistent file detection logic.The
setAntoraValue()function follows the same pattern asloadAntoraConfig(), ensuring consistency across the module.
139-167: LGTM: Function correctly migrated with dual extension support.The
getPrereleaseFromAntora()function follows the same file detection pattern as other functions in this module and safely returnsfalseon errors or when the file is missing. The strict equality check (prerelease === true) ensures only explicit booleantruevalues are treated as prerelease.
169-174: LGTM: Export list updated correctly.The
getPrereleaseFromAntorafunction is properly exported alongside existing utilities.tools/get-console-version.js (1)
7-7: LGTM: Import path correctly updated.The import path change aligns with the consolidation of utility functions into
antora-utils.js.tools/get-redpanda-version.js (1)
4-4: LGTM: Import path correctly updated.Consistent with the refactoring in
get-console-version.js, this import now points to the consolidatedantora-utils.jsmodule.bin/doc-tools.js (4)
1032-1037: LGTM: Improved command description.The updated description clearly communicates the default behavior (JSON extraction only) and the optional partial generation, which helps users understand the command's capabilities.
1143-1152: LGTM: Build sequence logic is correct.The conditional build logic properly handles all scenarios:
- Builds oldTag only when it exists and differs from newTag
- Always builds newTag (the primary target)
- Generates comparison report only when both tags exist and differ
- Logs and skips redundant operations when tags are identical
1154-1158: LGTM: Antora update logic correctly implements auto-update behavior.The conditional update (
!options.diff && !tagsAreSame) ensures that:
- Manual diffs (when user provides
--diff) don't trigger auto-updates- The config is only updated when there's actually a new tag to record
- The update only happens after successful builds (since
make()exits on failure)This aligns with the PR objective to keep documentation in sync with releases.
1082-1089: The Antora attribute path is correctly implemented and used consistently.The verification confirms that
'asciidoc.attributes.latest-redpanda-tag'is properly accessed across the codebase. ThegetAntoraValueandsetAntoraValuefunctions correctly handle the nested dot-path access, reading from and writing to the antora.yml/antora.yaml file at the expected structure. The attribute is consistently referenced in set-latest-version.js, replace-attributes-in-attachments.js, and doc-tools.js with no discrepancies.
Enhanced the property-docs CLI workflow:
--diffis not provided, the tool now automatically uses the latest Antora tag for diffing, streamlining version comparisons.--diffand--tagare the same, preventing redundant operations and unnecessary file changes..ymland.yamlAntora config files.