Improve documentation release workflow and refactor documentation site#507
Merged
Improve documentation release workflow and refactor documentation site#507
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughReplaces website-focused CI/docs with documentation-focused equivalents, adds a documentation release workflow and Makefile version-replacement logic, removes a legacy docs-update script and several standalone docs, and updates many documentation version tokens and links to Changes
Sequence Diagram(s)sequenceDiagram
participant Maintainer
participant GH_Actions as "GitHub Actions Runner"
participant Node as "Node / npm"
participant Git as "Git (repo & remote)"
participant Docs as "documentation/*"
Maintainer->>GH_Actions: workflow_dispatch(version, docker_tag)
GH_Actions->>Git: checkout repository
GH_Actions->>Node: setup Node.js & install deps (working-directory=documentation)
GH_Actions->>Docs: run Makefile versioning (two-phase sed replacements) and build
GH_Actions->>Git: git add/commit (if changes) -> push / open PR
GH_Actions-->>Maintainer: emit release summary (version, docker_tag, PR URL)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs-release.yml:
- Around line 128-134: The COMMIT_MSG is built with literal "\n" sequences so
the git commit -m will include backslashes instead of real newlines; update the
commit step that sets COMMIT_MSG (the variable and final git commit -m
"$COMMIT_MSG") to construct or pass a multi-line string correctly (e.g., use
printf to build COMMIT_MSG, or use echo -e or $'...' to expand escapes) so that
the commit message contains actual newlines and lists as intended.
In `@documentation/Makefile`:
- Around line 90-99: The update-version Makefile target uses macOS-only sed
syntax ("sed -i ''") — change the three sed invocations that operate on
versioned_docs/version-$(VERSION) and docs/_constants.md (the lines manipulating
DOCKER_TAG_NO_V, DOCKER_TAG and VERSION) to the same portable sed approach you
applied to the version target (i.e., avoid the macOS-only -i '' flag: use the
cross-platform pattern used in the other target such as creating a temporary
file or using -i.bak and removing backups), ensuring the replacements for
v0.0.0-dev, the non-prefixed 0.0.0-dev (using DOCKER_TAG_NO_V) and
latestVersion/quickStartDockerTag in docs/_constants.md are preserved.
- Around line 56-66: The Makefile uses macOS-only inplace sed syntax "sed -i ''"
in the version update steps (see the sed invocations replacing v0.0.0-dev and
updating docs/_constants.md and the DOCKER_TAG_NO_V/ VERSION usage), which
breaks on Linux CI; change these commands to a cross-platform approach: either
use a portable temp-file edit pattern (write sed output to a temp file and move
it back) or detect the OS at the top of the Makefile (UNAME_S) and set a
SED_INPLACE variable to use "sed -i ''" on Darwin and "sed -i" on Linux, then
replace direct "sed -i ''" calls in the versioned_docs and docs/_constants.md
lines with the SED_INPLACE variable.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 08267d07-745c-4fa0-886c-386f64e00214
⛔ Files ignored due to path filters (29)
documentation/docs/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-logs.pngis excluded by!**/*.pngdocumentation/package-lock.jsonis excluded by!**/package-lock.jsondocumentation/static/img/WSO2 Agent Manager Logo_Black.svgis excluded by!**/*.svgdocumentation/static/img/WSO2 Agent Manager Logo_white.svgis excluded by!**/*.svgdocumentation/static/img/WSO2-Logo.pngis excluded by!**/*.pngdocumentation/static/img/favicon.icois excluded by!**/*.icodocumentation/versioned_docs/version-v0.7.x/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/run-logs.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/run-logs.pngis excluded by!**/*.png
📒 Files selected for processing (110)
.github/scripts/update-docs-versions.sh.github/workflows/docs-deploy.yml.github/workflows/docs-pr-checks.yml.github/workflows/docs-release.yml.github/workflows/release.ymldocs/install/managed-cluster.mddocs/install/self-hosted-cluster.mddocs/quick-start.mddocumentation/.gitignoredocumentation/Makefiledocumentation/README.mddocumentation/docs/_constants.mddocumentation/docs/components/amp-instrumentation.mdxdocumentation/docs/concepts/evaluation.mdxdocumentation/docs/concepts/observability.mdxdocumentation/docs/contributing/contributing.mdxdocumentation/docs/getting-started/managed-cluster.mdxdocumentation/docs/getting-started/quick-start.mdxdocumentation/docs/getting-started/self-hosted-cluster.mdxdocumentation/docs/overview/what-is-amp.mdxdocumentation/docs/tutorials/evaluation-monitors.mdxdocumentation/docs/tutorials/observe-first-agent.mdxdocumentation/docusaurus.config.tsdocumentation/package.jsondocumentation/sidebars.tsdocumentation/src/components/DocIcon/index.tsxdocumentation/src/components/DocIcon/styles.module.cssdocumentation/src/components/DocMarkdownActions/index.tsxdocumentation/src/components/DocMarkdownActions/styles.module.cssdocumentation/src/components/HomepageFeatures/index.tsxdocumentation/src/components/HomepageFeatures/styles.module.cssdocumentation/src/components/Icon/index.tsxdocumentation/src/css/custom.cssdocumentation/src/pages/index.module.cssdocumentation/src/pages/index.tsxdocumentation/src/theme/DocItem/Layout/index.tsxdocumentation/src/theme/DocItem/Layout/styles.module.cssdocumentation/src/theme/Navbar/Content/index.tsxdocumentation/src/theme/Navbar/Content/styles.module.cssdocumentation/src/theme/SearchBar/index.tsxdocumentation/src/theme/SearchBar/styles.cssdocumentation/static/.nojekylldocumentation/tsconfig.jsondocumentation/versioned_docs/version-v0.3.0/_constants.mddocumentation/versioned_docs/version-v0.3.0/components/amp-api.mddocumentation/versioned_docs/version-v0.3.0/components/amp-console.mddocumentation/versioned_docs/version-v0.3.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.3.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.3.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.3.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.3.0/getting-started/single-cluster-installation.mddocumentation/versioned_docs/version-v0.3.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.4.0/_constants.mddocumentation/versioned_docs/version-v0.4.0/components/amp-api.mddocumentation/versioned_docs/version-v0.4.0/components/amp-console.mddocumentation/versioned_docs/version-v0.4.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.4.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.4.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.4.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.4.0/getting-started/single-cluster-installation.mddocumentation/versioned_docs/version-v0.4.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.5.0/_constants.mddocumentation/versioned_docs/version-v0.5.0/components/amp-api.mddocumentation/versioned_docs/version-v0.5.0/components/amp-console.mddocumentation/versioned_docs/version-v0.5.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.5.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.5.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.5.0/getting-started/managed-cluster.mddocumentation/versioned_docs/version-v0.5.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.5.0/getting-started/self-hosted-cluster.mddocumentation/versioned_docs/version-v0.5.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.6.x/_constants.mddocumentation/versioned_docs/version-v0.6.x/components/amp-api.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-console.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-trace-observer.mdxdocumentation/versioned_docs/version-v0.6.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.6.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.7.x/_constants.mddocumentation/versioned_docs/version-v0.7.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.7.x/concepts/evaluation.mdxdocumentation/versioned_docs/version-v0.7.x/concepts/observability.mdxdocumentation/versioned_docs/version-v0.7.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.7.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.7.x/tutorials/evaluation-monitors.mdxdocumentation/versioned_docs/version-v0.7.x/tutorials/observe-first-agent.mdxdocumentation/versioned_docs/version-v0.8.x/_constants.mddocumentation/versioned_docs/version-v0.8.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.8.x/concepts/evaluation.mdxdocumentation/versioned_docs/version-v0.8.x/concepts/observability.mdxdocumentation/versioned_docs/version-v0.8.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.8.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.8.x/tutorials/evaluation-monitors.mdxdocumentation/versioned_docs/version-v0.8.x/tutorials/observe-first-agent.mdxdocumentation/versioned_sidebars/version-v0.3.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.4.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.5.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.6.x-sidebars.jsondocumentation/versioned_sidebars/version-v0.7.x-sidebars.jsondocumentation/versioned_sidebars/version-v0.8.x-sidebars.jsondocumentation/versions.json
💤 Files with no reviewable changes (5)
- .github/workflows/release.yml
- docs/quick-start.md
- docs/install/managed-cluster.md
- docs/install/self-hosted-cluster.md
- .github/scripts/update-docs-versions.sh
AnoshanJ
changed the title
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
documentation/Makefile (1)
59-74:⚠️ Potential issue | 🟠 MajorFail the
versiontarget as soon as snapshot creation fails.This whole
if ... else ... fibranch runs in one shell. Ifnpm run docusaurus docs:version $(VERSION)returns non-zero, the laterechocommands can still make the recipe look successful, and the release workflow will continue from a broken snapshot. Addset -einside theelsebranch or chain the post-processing with&&.🔧 Minimal fix
else \ + set -e; \ npm run docusaurus docs:version $(VERSION); \ echo "Replacing version placeholders in versioned docs..."; \🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@documentation/Makefile` around lines 59 - 74, The recipe for creating a new docs version can continue after a failed snapshot because the commands in the else branch run in a single shell without exit-on-error; modify the else branch of the VERSION creation block so that failures stop the recipe — either add `set -e` at the top of the else block (so `npm run docusaurus docs:version $(VERSION)` and subsequent commands fail-fast) or chain the post-processing commands with `&&` after `npm run docusaurus docs:version $(VERSION)`; ensure the commands that use DOCKER_TAG, DOCKER_TAG_NO_V, SED_INPLACE and updates to docs/_constants.md only run when the docs:version command succeeded.
🧹 Nitpick comments (1)
documentation/Makefile (1)
64-71: Extract the rewrite/update block into one helper.Both targets now duplicate the same placeholder replacements and
_constants.mdupdates. A shared macro or private target would keep the rules in one place and reduce drift the next time these patterns change.Also applies to: 98-105
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@documentation/Makefile` around lines 64 - 71, Extract the repeated sed replacement logic into a single Makefile helper (either a private target like "._update-versioned-docs" or a macro variable) and replace the duplicated blocks that compute DOCKER_TAG_NO_V and run the four $(SED_INPLACE) commands with calls to that helper; ensure the helper accepts or uses VERSION and DOCKER_TAG (and SED_INPLACE) and performs the two find+sed replacements plus the two $(SED_INPLACE) edits to docs/_constants.md so both locations (the current block and the duplicated block around lines 98-105) invoke the same helper instead of duplicating the commands.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs-release.yml:
- Around line 25-45: The current validation only checks formats; update the
"Validate inputs" step to also compare VERSION and DOCKER_TAG semantics: parse
major.minor (and patch if present) from VERSION and DOCKER_TAG (use the existing
regex matches on VERSION and DOCKER_TAG), then if VERSION contains an "x"
require DOCKER_TAG's major and minor to match VERSION's major and minor, and if
VERSION is fully pinned (no "x") require exact equality between VERSION and
DOCKER_TAG; on mismatch print a clear error and exit 1. Ensure you use the
existing VERSION and DOCKER_TAG variables and keep the existing format checks
before performing this semantic comparison.
- Around line 81-102: Add reliable failure handling and accurate placeholder
checks to the verification step: enable set -o pipefail at the top of the step,
replace the fragile "grep ... | wc -l || echo '0'" constructs with a safe count
(e.g., use grep -r -E "v?0\.0\.0-dev" versioned_docs/version-$VERSION/ | wc -l
or grep -r -c -E "v?0\.0\.0-dev" and ensure the count is numeric) to populate
PLACEHOLDER_COUNT, check for both forms (v0.0.0-dev and 0.0.0-dev) using the -E
pattern or two greps, and if PLACEHOLDER_COUNT -gt 0 then print matches and exit
1 so the job fails; also verify docs/_constants.md contains the expected values
(for example check for $DOCKER_TAG or specific constants with grep -q and exit 1
if missing) instead of just catting the file.
---
Outside diff comments:
In `@documentation/Makefile`:
- Around line 59-74: The recipe for creating a new docs version can continue
after a failed snapshot because the commands in the else branch run in a single
shell without exit-on-error; modify the else branch of the VERSION creation
block so that failures stop the recipe — either add `set -e` at the top of the
else block (so `npm run docusaurus docs:version $(VERSION)` and subsequent
commands fail-fast) or chain the post-processing commands with `&&` after `npm
run docusaurus docs:version $(VERSION)`; ensure the commands that use
DOCKER_TAG, DOCKER_TAG_NO_V, SED_INPLACE and updates to docs/_constants.md only
run when the docs:version command succeeded.
---
Nitpick comments:
In `@documentation/Makefile`:
- Around line 64-71: Extract the repeated sed replacement logic into a single
Makefile helper (either a private target like "._update-versioned-docs" or a
macro variable) and replace the duplicated blocks that compute DOCKER_TAG_NO_V
and run the four $(SED_INPLACE) commands with calls to that helper; ensure the
helper accepts or uses VERSION and DOCKER_TAG (and SED_INPLACE) and performs the
two find+sed replacements plus the two $(SED_INPLACE) edits to
docs/_constants.md so both locations (the current block and the duplicated block
around lines 98-105) invoke the same helper instead of duplicating the commands.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 31511c3f-8821-4902-837c-8a14e92526d3
📒 Files selected for processing (2)
.github/workflows/docs-release.ymldocumentation/Makefile
AnoshanJ
force-pushed
the
feat/doc-improvements-0.8
branch
from
9830ab4 to
8cc1805
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
.github/workflows/docs-release.yml (1)
62-65:⚠️ Potential issue | 🟠 MajorPinned-version validation still allows prerelease docker tags.
For pinned
VERSIONvalues, the current check stripsDOCKER_TAGprerelease suffix before comparison, sov0.8.0andv0.8.0-rc.1are treated as equal. That defeats strict pinning.🔧 Suggested fix
- else - # VERSION is fully pinned (e.g., v0.8.0) — require exact match - if [[ "v${V_MAJOR}.${V_MINOR}.${V_PATCH}" != "v${DT_MAJOR}.${DT_MINOR}.${DT_PATCH}" ]]; then - echo "Error: Fully pinned VERSION $VERSION must match DOCKER_TAG $DOCKER_TAG (ignoring pre-release suffix)" - exit 1 - fi - fi + else + # VERSION is fully pinned (e.g., v0.8.0) — require exact match + if [[ "$VERSION" != "$DOCKER_TAG" ]]; then + echo "Error: Fully pinned VERSION $VERSION must exactly match DOCKER_TAG $DOCKER_TAG" + exit 1 + fi + fi#!/bin/bash set -euo pipefail VERSION=v0.8.0 DOCKER_TAG=v0.8.0-rc.1 V_MAJOR="${VERSION#v}"; V_MAJOR="${V_MAJOR%%.*}" V_MINOR="${VERSION#v*.}"; V_MINOR="${V_MINOR%%.*}" V_PATCH="${VERSION##*.}" DT_NO_PREFIX="${DOCKER_TAG#v}" DT_MAJOR="${DT_NO_PREFIX%%.*}" DT_REST="${DT_NO_PREFIX#*.}" DT_MINOR="${DT_REST%%.*}" DT_PATCH="${DT_REST#*.}" DT_PATCH="${DT_PATCH%%-*}" if [[ "v${V_MAJOR}.${V_MINOR}.${V_PATCH}" == "v${DT_MAJOR}.${DT_MINOR}.${DT_PATCH}" ]]; then echo "Current logic accepts pinned VERSION with prerelease DOCKER_TAG" else echo "Current logic rejects it" fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/docs-release.yml around lines 62 - 65, The current pinned-VERSION check strips DOCKER_TAG prerelease suffix (the logic that computes DT_PATCH/DT_NO_PREFIX) so vX.Y.Z matches vX.Y.Z-rc.1; update the comparison to require exact equality with the full DOCKER_TAG (or ensure DT_PATCH keeps the prerelease segment) so that "v${V_MAJOR}.${V_MINOR}.${V_PATCH}" must equal "${DOCKER_TAG}" exactly when VERSION is fully pinned; modify the DT parsing or the if-condition that compares VERSION and DOCKER_TAG to reject any DOCKER_TAG containing a prerelease suffix (e.g., detect a '-' in DOCKER_TAG and fail) and keep references to V_MAJOR, V_MINOR, V_PATCH, DT_MAJOR, DT_MINOR, DT_PATCH, DOCKER_TAG, and VERSION when applying the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs-release.yml:
- Around line 77-83: The workflow can be triggered from non-main branches but
the checkout step (uses: actions/checkout@v4) does not pin a branch while the
push action later always pushes to main, allowing feature-branch content to be
pushed into main; fix by pinning the checkout to the main branch (add ref:
refs/heads/main or ref: ${{ github.event.repository.default_branch }}) in the
checkout step or restrict workflow_dispatch to only run on main
(workflow_dispatch: branches: [main]), ensuring the code checked out matches the
branch you intend to push to.
---
Duplicate comments:
In @.github/workflows/docs-release.yml:
- Around line 62-65: The current pinned-VERSION check strips DOCKER_TAG
prerelease suffix (the logic that computes DT_PATCH/DT_NO_PREFIX) so vX.Y.Z
matches vX.Y.Z-rc.1; update the comparison to require exact equality with the
full DOCKER_TAG (or ensure DT_PATCH keeps the prerelease segment) so that
"v${V_MAJOR}.${V_MINOR}.${V_PATCH}" must equal "${DOCKER_TAG}" exactly when
VERSION is fully pinned; modify the DT parsing or the if-condition that compares
VERSION and DOCKER_TAG to reject any DOCKER_TAG containing a prerelease suffix
(e.g., detect a '-' in DOCKER_TAG and fail) and keep references to V_MAJOR,
V_MINOR, V_PATCH, DT_MAJOR, DT_MINOR, DT_PATCH, DOCKER_TAG, and VERSION when
applying the change.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 590eca38-b2ce-4cea-81d9-af2464fb4c8e
⛔ Files ignored due to path filters (11)
documentation/docs/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-logs.pngis excluded by!**/*.pngdocumentation/package-lock.jsonis excluded by!**/package-lock.jsondocumentation/static/img/WSO2 Agent Manager Logo_Black.svgis excluded by!**/*.svgdocumentation/static/img/WSO2 Agent Manager Logo_white.svgis excluded by!**/*.svg
📒 Files selected for processing (42)
.github/scripts/update-docs-versions.sh.github/workflows/docs-deploy.yml.github/workflows/docs-pr-checks.yml.github/workflows/docs-release.yml.github/workflows/release.ymldocs/install/managed-cluster.mddocs/install/self-hosted-cluster.mddocs/quick-start.mddocumentation/.gitignoredocumentation/Makefiledocumentation/README.mddocumentation/docs/_constants.mddocumentation/docs/components/amp-instrumentation.mdxdocumentation/docs/concepts/evaluation.mdxdocumentation/docs/concepts/observability.mdxdocumentation/docs/contributing/contributing.mdxdocumentation/docs/getting-started/managed-cluster.mdxdocumentation/docs/getting-started/quick-start.mdxdocumentation/docs/getting-started/self-hosted-cluster.mdxdocumentation/docs/overview/what-is-amp.mdxdocumentation/docs/tutorials/evaluation-monitors.mdxdocumentation/docs/tutorials/observe-first-agent.mdxdocumentation/docusaurus.config.tsdocumentation/package.jsondocumentation/sidebars.tsdocumentation/src/components/DocIcon/index.tsxdocumentation/src/components/DocIcon/styles.module.cssdocumentation/src/components/DocMarkdownActions/index.tsxdocumentation/src/components/DocMarkdownActions/styles.module.cssdocumentation/src/components/HomepageFeatures/index.tsxdocumentation/src/components/HomepageFeatures/styles.module.cssdocumentation/src/components/Icon/index.tsxdocumentation/src/css/custom.cssdocumentation/src/pages/index.module.cssdocumentation/src/pages/index.tsxdocumentation/src/theme/DocItem/Layout/index.tsxdocumentation/src/theme/DocItem/Layout/styles.module.cssdocumentation/src/theme/Navbar/Content/index.tsxdocumentation/src/theme/Navbar/Content/styles.module.cssdocumentation/src/theme/SearchBar/index.tsxdocumentation/src/theme/SearchBar/styles.cssdocumentation/static/.nojekyll
💤 Files with no reviewable changes (5)
- docs/quick-start.md
- .github/workflows/release.yml
- docs/install/self-hosted-cluster.md
- docs/install/managed-cluster.md
- .github/scripts/update-docs-versions.sh
🚧 Files skipped from review as they are similar to previous changes (4)
- documentation/docs/getting-started/self-hosted-cluster.mdx
- documentation/docs/getting-started/quick-start.mdx
- .github/workflows/docs-pr-checks.yml
- documentation/docusaurus.config.ts
Comment on lines
+77
to
+83
| - name: Checkout code | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| persist-credentials: true | ||
| fetch-depth: 0 | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C2 'actions/checkout@v4|ref:|git push origin main' .github/workflows/docs-release.yml
Repository: wso2/agent-manager
Length of output: 44
🏁 Script executed:
fd -type f 'docs-release.yml' .github/
Repository: wso2/agent-manager
Length of output: 232
🏁 Script executed:
wc -l .github/workflows/docs-release.yml
Repository: wso2/agent-manager
Length of output: 100
🏁 Script executed:
cat -n .github/workflows/docs-release.yml | head -100
Repository: wso2/agent-manager
Length of output: 4095
🏁 Script executed:
cat -n .github/workflows/docs-release.yml | sed -n '100,202p'
Repository: wso2/agent-manager
Length of output: 5404
Workflow can push non-main dispatch content into main.
workflow_dispatch can run from any branch, but checkout at line 77-82 is not pinned while push at line 176 is hardcoded to main. This allows feature branch code to be committed to main if the workflow is triggered from a non-main branch.
🔧 Suggested hardening
- name: Checkout code
uses: actions/checkout@v4
with:
+ ref: main
token: ${{ secrets.GITHUB_TOKEN }}
persist-credentials: true
fetch-depth: 0
...
- git push origin main
+ git push origin HEAD:main
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/docs-release.yml around lines 77 - 83, The workflow can be
triggered from non-main branches but the checkout step (uses:
actions/checkout@v4) does not pin a branch while the push action later always
pushes to main, allowing feature-branch content to be pushed into main; fix by
pinning the checkout to the main branch (add ref: refs/heads/main or ref: ${{
github.event.repository.default_branch }}) in the checkout step or restrict
workflow_dispatch to only run on main (workflow_dispatch: branches: [main]),
ensuring the code checked out matches the branch you intend to push to.
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
documentation/docs/tutorials/observe-first-agent.mdx (1)
64-65: Tighten env-var instruction wording for clarity.“Set the above env variables.” is a bit vague; use explicit “export … in the same shell session before running”.
✏️ Suggested wording update
-Set the above env variables. +Export these environment variables in the same shell session before running your agent.-Set the above env variables. +Export these environment variables in the same shell session before running your Ballerina program.Also applies to: 131-132
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@documentation/docs/tutorials/observe-first-agent.mdx` around lines 64 - 65, Replace the vague sentence "Set the above env variables." in documentation/docs/tutorials/observe-first-agent.mdx (occurrences around lines 64–65 and 131–132) with a clearer instruction that tells users to export the variables in the same shell session before running the commands, e.g., instruct to run "export VAR=value" (or set in Windows equivalent) in the same terminal where they will execute the tutorial commands so the environment is available to the process.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@documentation/docs/tutorials/observe-first-agent.mdx`:
- Around line 64-65: Replace the vague sentence "Set the above env variables."
in documentation/docs/tutorials/observe-first-agent.mdx (occurrences around
lines 64–65 and 131–132) with a clearer instruction that tells users to export
the variables in the same shell session before running the commands, e.g.,
instruct to run "export VAR=value" (or set in Windows equivalent) in the same
terminal where they will execute the tutorial commands so the environment is
available to the process.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0454cb90-8255-40c5-a007-f9c106e6c35f
📒 Files selected for processing (1)
documentation/docs/tutorials/observe-first-agent.mdx
AnoshanJ
requested review from
hanzjk and
menakaj
and removed request for
hanzjk
Member
Review Note: Workflow pushes directly to
|
AnoshanJ
force-pushed
the
feat/doc-improvements-0.8
branch
from
be92c70 to
681d4dc
Compare
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
documentation/docs/tutorials/observe-first-agent.mdx (1)
41-88:⚠️ Potential issue | 🟡 MinorReplace Markdown headings with HTML headings inside tab-only sections to exclude them from the page TOC.
Docusaurus includes headings inside
<TabItem>in the generated table of contents at build time, mixing Python and Ballerina steps together. Users clicking these TOC links see inactive tabs without visible content. Use<h3>4.1 Install AMP Instrumentation Package</h3>instead of### 4.1 Install AMP Instrumentation Packagefor all substeps in both language panes to keep them out of the TOC.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@documentation/docs/tutorials/observe-first-agent.mdx` around lines 41 - 88, The Markdown subheadings (e.g., "### 4.1 Install AMP Instrumentation Package", "### 4.2 Generate an API Key", "### 4.3 Set Environment Variables", "### 4.4 Run Your Agent with Instrumentation") inside the tab-only sections should be replaced with explicit HTML headings (e.g., <h3>4.1 Install AMP Instrumentation Package</h3>, etc.) so they are not picked up by Docusaurus TOC; update each "### ..." line in the tab panes to the corresponding <h3>...</h3> form (including all substep headings in both language panes) while leaving the rest of the content and code blocks unchanged.
🧹 Nitpick comments (2)
.github/workflows/docs-release.yml (1)
78-83: Consider pinning checkout tomainbranch.The checkout step doesn't specify a
ref, so ifworkflow_dispatchis triggered from a non-main branch, the documentation snapshot will be based on that branch's state rather thanmain. While the PR-based approach allows reviewers to catch this, explicitly pinning tomainwould prevent accidental releases from feature branches.🔧 Proposed fix
- name: Checkout code uses: actions/checkout@v4 with: + ref: main token: ${{ secrets.GITHUB_TOKEN }} persist-credentials: true fetch-depth: 0🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/docs-release.yml around lines 78 - 83, The checkout step using actions/checkout@v4 currently omits a ref so workflows triggered from non-main branches can checkout that branch; update the Checkout code block for actions/checkout@v4 to explicitly set ref: main so the workflow always checks out the main branch (modify the step that contains uses: actions/checkout@v4 and with: token/persist-credentials/fetch-depth to include ref: main).documentation/docs/tutorials/observe-first-agent.mdx (1)
38-38: Consider a sharedgroupIdfor these language tabs.If other docs also use the same Python/Ballerina split, adding a namespaced
groupIdhere lets Docusaurus sync that choice across tab groups and persist it inlocalStorage.groupIds are globally namespaced, so something specific likeagent-languageis safer than a generic name. (docusaurus.io)♻️ Suggested tweak
-<Tabs> +<Tabs groupId="agent-language">🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@documentation/docs/tutorials/observe-first-agent.mdx` at line 38, The Tabs component in observe-first-agent.mdx should include a namespaced groupId so the language selection persists across tab groups; update the <Tabs> element to add a globally unique groupId (e.g., "agent-language") and ensure other docs using the same Python/Ballerina split use the same groupId so Docusaurus can sync and persist the selection in localStorage.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@documentation/docs/tutorials/observe-first-agent.mdx`:
- Around line 41-88: The Markdown subheadings (e.g., "### 4.1 Install AMP
Instrumentation Package", "### 4.2 Generate an API Key", "### 4.3 Set
Environment Variables", "### 4.4 Run Your Agent with Instrumentation") inside
the tab-only sections should be replaced with explicit HTML headings (e.g.,
<h3>4.1 Install AMP Instrumentation Package</h3>, etc.) so they are not picked
up by Docusaurus TOC; update each "### ..." line in the tab panes to the
corresponding <h3>...</h3> form (including all substep headings in both language
panes) while leaving the rest of the content and code blocks unchanged.
---
Nitpick comments:
In @.github/workflows/docs-release.yml:
- Around line 78-83: The checkout step using actions/checkout@v4 currently omits
a ref so workflows triggered from non-main branches can checkout that branch;
update the Checkout code block for actions/checkout@v4 to explicitly set ref:
main so the workflow always checks out the main branch (modify the step that
contains uses: actions/checkout@v4 and with:
token/persist-credentials/fetch-depth to include ref: main).
In `@documentation/docs/tutorials/observe-first-agent.mdx`:
- Line 38: The Tabs component in observe-first-agent.mdx should include a
namespaced groupId so the language selection persists across tab groups; update
the <Tabs> element to add a globally unique groupId (e.g., "agent-language") and
ensure other docs using the same Python/Ballerina split use the same groupId so
Docusaurus can sync and persist the selection in localStorage.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 852059cf-ca00-4000-be4e-8f059b7bd3e3
⛔ Files ignored due to path filters (29)
documentation/docs/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/docs/img/evaluation/run-logs.pngis excluded by!**/*.pngdocumentation/package-lock.jsonis excluded by!**/package-lock.jsondocumentation/static/img/WSO2 Agent Manager Logo_Black.svgis excluded by!**/*.svgdocumentation/static/img/WSO2 Agent Manager Logo_white.svgis excluded by!**/*.svgdocumentation/static/img/WSO2-Logo.pngis excluded by!**/*.pngdocumentation/static/img/favicon.icois excluded by!**/*.icodocumentation/versioned_docs/version-v0.7.x/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.7.x/img/evaluation/run-logs.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/create-step1.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/create-step2-evaluators.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/evaluation-tab.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/evaluator-drawer.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/llm-provider-config.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/monitor-dashboard.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/run-history.pngis excluded by!**/*.pngdocumentation/versioned_docs/version-v0.8.x/img/evaluation/run-logs.pngis excluded by!**/*.png
📒 Files selected for processing (108)
.github/scripts/update-docs-versions.sh.github/workflows/docs-deploy.yml.github/workflows/docs-pr-checks.yml.github/workflows/docs-release.yml.github/workflows/release.ymldocs/install/managed-cluster.mddocs/install/self-hosted-cluster.mddocs/quick-start.mddocumentation/.gitignoredocumentation/Makefiledocumentation/README.mddocumentation/docs/_constants.mddocumentation/docs/components/amp-instrumentation.mdxdocumentation/docs/concepts/evaluation.mdxdocumentation/docs/concepts/observability.mdxdocumentation/docs/contributing/contributing.mdxdocumentation/docs/getting-started/managed-cluster.mdxdocumentation/docs/getting-started/quick-start.mdxdocumentation/docs/getting-started/self-hosted-cluster.mdxdocumentation/docs/overview/what-is-amp.mdxdocumentation/docs/tutorials/evaluation-monitors.mdxdocumentation/docs/tutorials/observe-first-agent.mdxdocumentation/docusaurus.config.tsdocumentation/package.jsondocumentation/sidebars.tsdocumentation/src/components/DocIcon/index.tsxdocumentation/src/components/DocIcon/styles.module.cssdocumentation/src/components/DocMarkdownActions/index.tsxdocumentation/src/components/DocMarkdownActions/styles.module.cssdocumentation/src/components/HomepageFeatures/index.tsxdocumentation/src/components/HomepageFeatures/styles.module.cssdocumentation/src/components/Icon/index.tsxdocumentation/src/css/custom.cssdocumentation/src/pages/index.module.cssdocumentation/src/pages/index.tsxdocumentation/src/theme/DocItem/Layout/index.tsxdocumentation/src/theme/DocItem/Layout/styles.module.cssdocumentation/src/theme/Navbar/Content/index.tsxdocumentation/src/theme/Navbar/Content/styles.module.cssdocumentation/src/theme/SearchBar/index.tsxdocumentation/src/theme/SearchBar/styles.cssdocumentation/static/.nojekylldocumentation/tsconfig.jsondocumentation/versioned_docs/version-v0.3.0/_constants.mddocumentation/versioned_docs/version-v0.3.0/components/amp-api.mddocumentation/versioned_docs/version-v0.3.0/components/amp-console.mddocumentation/versioned_docs/version-v0.3.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.3.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.3.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.3.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.3.0/getting-started/single-cluster-installation.mddocumentation/versioned_docs/version-v0.3.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.4.0/_constants.mddocumentation/versioned_docs/version-v0.4.0/components/amp-api.mddocumentation/versioned_docs/version-v0.4.0/components/amp-console.mddocumentation/versioned_docs/version-v0.4.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.4.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.4.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.4.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.4.0/getting-started/single-cluster-installation.mddocumentation/versioned_docs/version-v0.4.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.5.0/_constants.mddocumentation/versioned_docs/version-v0.5.0/components/amp-api.mddocumentation/versioned_docs/version-v0.5.0/components/amp-console.mddocumentation/versioned_docs/version-v0.5.0/components/amp-instrumentation.mddocumentation/versioned_docs/version-v0.5.0/components/amp-trace-observer.mddocumentation/versioned_docs/version-v0.5.0/contributing/contributing.mddocumentation/versioned_docs/version-v0.5.0/getting-started/managed-cluster.mddocumentation/versioned_docs/version-v0.5.0/getting-started/quick-start.mddocumentation/versioned_docs/version-v0.5.0/getting-started/self-hosted-cluster.mddocumentation/versioned_docs/version-v0.5.0/overview/what-is-amp.mddocumentation/versioned_docs/version-v0.6.x/_constants.mddocumentation/versioned_docs/version-v0.6.x/components/amp-api.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-console.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.6.x/components/amp-trace-observer.mdxdocumentation/versioned_docs/version-v0.6.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.6.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.6.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.7.x/_constants.mddocumentation/versioned_docs/version-v0.7.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.7.x/concepts/evaluation.mdxdocumentation/versioned_docs/version-v0.7.x/concepts/observability.mdxdocumentation/versioned_docs/version-v0.7.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.7.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.7.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.7.x/tutorials/evaluation-monitors.mdxdocumentation/versioned_docs/version-v0.7.x/tutorials/observe-first-agent.mdxdocumentation/versioned_docs/version-v0.8.x/_constants.mddocumentation/versioned_docs/version-v0.8.x/components/amp-instrumentation.mdxdocumentation/versioned_docs/version-v0.8.x/concepts/evaluation.mdxdocumentation/versioned_docs/version-v0.8.x/concepts/observability.mdxdocumentation/versioned_docs/version-v0.8.x/contributing/contributing.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/managed-cluster.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/quick-start.mdxdocumentation/versioned_docs/version-v0.8.x/getting-started/self-hosted-cluster.mdxdocumentation/versioned_docs/version-v0.8.x/overview/what-is-amp.mdxdocumentation/versioned_docs/version-v0.8.x/tutorials/evaluation-monitors.mdxdocumentation/versioned_docs/version-v0.8.x/tutorials/observe-first-agent.mdxdocumentation/versioned_sidebars/version-v0.3.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.4.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.5.0-sidebars.jsondocumentation/versioned_sidebars/version-v0.6.x-sidebars.jsondocumentation/versioned_sidebars/version-v0.7.x-sidebars.json
💤 Files with no reviewable changes (5)
- .github/scripts/update-docs-versions.sh
- docs/install/self-hosted-cluster.md
- .github/workflows/release.yml
- docs/install/managed-cluster.md
- docs/quick-start.md
✅ Files skipped from review due to trivial changes (1)
- documentation/versioned_docs/version-v0.8.x/getting-started/quick-start.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- documentation/docusaurus.config.ts
- documentation/docs/getting-started/quick-start.mdx
Contributor
Author
|
The documentation workflow is updated based on the comments: Push to a branch and auto-create a PR |
AnoshanJ
force-pushed
the
feat/doc-improvements-0.8
branch
from
681d4dc to
435d46a
Compare
…plement unique branch creation for PRs, and improve summary output.
AnoshanJ
force-pushed
the
feat/doc-improvements-0.8
branch
from
435d46a to
9d38564
Compare
a5anka
reviewed
Mar 19, 2026
Member
a5anka
left a comment
a5anka
left a comment
There was a problem hiding this comment.
Observation on docs/_constants.md mutation during versioning (documentation/Makefile lines 70–71, 104–105)
The version and update-version targets update docs/_constants.md (the "Next"/unreleased version source) with the release version values:
$(SED_INPLACE) "s/latestVersion: '.*'/latestVersion: '$(VERSION)'/" docs/_constants.md;
$(SED_INPLACE) "s/quickStartDockerTag: '.*'/quickStartDockerTag: '$(DOCKER_TAG)'/" docs/_constants.md;
This means after a release, the "Next" docs will show the last released version in their constants (e.g., v0.9.x / v0.9.0) rather than the dev placeholder (v0.0.0-dev). A few implications to be aware of:
-
After the release workflow runs and merges, the
docs/_constants.mdonmainwill permanently carry the released version, not a dev placeholder. This is fine if intentional — it means the site's announcement bar and footer links always reference the latest release. -
However, if someone later adds new doc content referencing version-specific URLs/tags in the "Next" docs, they need to know they should use
v0.0.0-devplaceholders in the markdown files themselves, but_constants.mdwill not use placeholders — it will carry the latest release values. This is a subtle distinction that could cause confusion for contributors. -
The
docusaurus.config.tsalso readsquickStartDockerTagfrom_constants.mdat build time for the announcement bar, so this coupling is load-bearing.
Suggestion: Consider either:
- Documenting this behavior (e.g., a comment in
_constants.mdexplaining it gets updated by the release workflow), or - Resetting
_constants.mdback to dev placeholders after the versioned snapshot is created, so "Next" always shows dev values and the released version only lives in the versioned snapshot.
a5anka
approved these changes
Mar 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Add documentation product release workflow. Documentation versions are now managed independently via the Makefile or the new
docs-releaseGitHub workflow, usingv0.0.0-devplaceholders that get replaced with actual versions when creating versioned snapshots. This ensures the published site always shows real version references while the "Next" (unreleased) docs use dev placeholders.Resolves #389
Summary
website/docs/to usev0.0.0-devplaceholders for deterministic version updates during releasesdocumentation/Makefile(versionandupdate-versiontargets)docs-release.ymlworkflow for manually triggering documentation releases via GitHub Actionsupdate-docs-versions.shscript and its step from the release workflowwebsite/folder todocumentation/and update all workflow referencesdocs/folderGoals
Approach
User stories
Release note
Documentation
Training
Certification
Marketing
Automation tests
Security checks
Samples
Related PRs
Migrations (if applicable)
Test environment
Learning
Summary by CodeRabbit
Documentation
Chores