fix(docs): correct stale version pins and prevent next.yaml drift#589
fix(docs): correct stale version pins and prevent next.yaml drift#589myasnikovdaniil wants to merge 5 commits into
Conversation
The Go types `go get` example hardcoded @v1.2.0, and data/versions/v1.5.yaml
was a stale copy of next.yaml — so every {{< version-pin >}} on the default
(v1.5) docs rendered cozystack v1.3.0 / Talos v1.12.6 instead of v1.5.0 /
v1.13.0.
- Fix data/versions/v1.5.yaml to the real v1.5 pins
- Add data/versions/v1.2.yaml; switch v1.2 go-types to version-pin
(v1.0/v1.1 keep the literal — the api submodule's earliest tag is v1.2.0)
- Harden release_next.sh to rewrite cozystack_version/tag from RELEASE_TAG
so a stale next.yaml can't freeze the wrong version into a release again
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
next.yaml had been stale at cozystack v1.3.0 / Talos v1.12.6 since the v1.3 cycle because nothing refreshed it. Add hack/update_versions.sh to regenerate it from cozystack/cozystack (Talos from the installer profile, cozystack tag from the latest release) and wire it into `make update-all` for the next trunk, so it can no longer go stale. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
The version-mismatch warning hardcoded "Cozystack v1.3.0 ... target Talos
v1.12", which renders wrong on v1.4/v1.5 (both ship Talos v1.13). Replace the
literals with the {{< version-pin >}} shortcodes already used elsewhere in the
file, across next/v1.5/v1.4/v1.3.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
myasnikovdaniil
requested review from
Andrei Kvapil (kvaps) and
Timofei Larkin (lllamnyp)
as code owners
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
More reviews will be available in 43 minutes and 35 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses rolling per-developer review limits. Reviews become available again as older review attempts age out of the rolling limit window. Please see our Fair Usage Limits Policy for further information. 📝 WalkthroughWalkthroughAdds ChangesAutomated Version-Pin Generation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request automates the management of pinned upstream-tool versions in the documentation. It introduces a new script hack/update_versions.sh to fetch versions from upstream, integrates it into the Makefile, and replaces hardcoded version strings with the {{< version-pin >}} shortcode in several markdown files. Feedback on the changes suggests improving the robustness of hack/update_versions.sh by appending || true to the curl pipeline to prevent premature exits under set -e, and replacing the GNU-specific sort -V with a POSIX-compliant sorting method to ensure compatibility on macOS.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| # -------------------- 1. Talos version from the installer profile -------------------- | ||
| INSTALLER_PATH="packages/core/talos/images/talos/profiles/installer.yaml" | ||
| INSTALLER_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/${INSTALLER_PATH}" | ||
| talos="$(curl -fsSL "$INSTALLER_URL" 2>/dev/null | awk '/^version:[[:space:]]/{print $2; exit}')" |
There was a problem hiding this comment.
Because set -o pipefail and set -e are enabled, if the curl command fails (e.g., due to a network issue, rate limit, or invalid branch), the entire pipeline will return a non-zero exit code. This causes the shell to exit immediately, preventing the script from reaching the subsequent validation block and printing the helpful error message.
Appending || true to the pipeline inside the subshell allows the script to continue and gracefully handle the failure in the validation block.
| talos="$(curl -fsSL "$INSTALLER_URL" 2>/dev/null | awk '/^version:[[:space:]]/{print $2; exit}')" | |
| talos="$(curl -fsSL "$INSTALLER_URL" 2>/dev/null | awk '/^version:[[:space:]]/{print $2; exit}' || true)" |
There was a problem hiding this comment.
Good catch — confirmed: under set -e + set -o pipefail, a failed curl made the command substitution exit the script before the validation block, so the intended error message never printed. Added || true to the pipeline so a fetch failure now falls through to the validation check. Fixed in 949bc63.
| COZYSTACK_TAG="$(git ls-remote --tags --refs "https://github.com/${SOURCE_REPO}.git" 'v*.*.*' \ | ||
| | awk -F/ '/refs\/tags\/v[0-9]+\.[0-9]+\.[0-9]+$/{print $NF}' \ | ||
| | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)" |
There was a problem hiding this comment.
The sort -V (version sort) option is a GNU extension and is not supported by the default sort utility on macOS (BSD sort). Running this script on macOS will result in a sort: invalid option -- V error.
To make the script portable across both Linux and macOS, we can strip the v prefix, use standard POSIX numeric sort (sort -t. -k 1,1n -k 2,2n -k 3,3n), and then prepend the v back. This also allows us to safely handle pipeline failures with || true so the script can print a clear error message if git ls-remote fails.
| COZYSTACK_TAG="$(git ls-remote --tags --refs "https://github.com/${SOURCE_REPO}.git" 'v*.*.*' \ | |
| | awk -F/ '/refs\/tags\/v[0-9]+\.[0-9]+\.[0-9]+$/{print $NF}' \ | |
| | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)" | |
| COZYSTACK_TAG="$(git ls-remote --tags --refs "https://github.com/${SOURCE_REPO}.git" 'v*.*.*' \ | |
| | awk -F/ '/refs\/tags\/v[0-9]+\.[0-9]+\.[0-9]+$/{print $NF}' \ | |
| | sed 's/^v//' | sort -t. -k 1,1n -k 2,2n -k 3,3n | sed 's/^/v/' | tail -1 || true)" |
There was a problem hiding this comment.
Applied the || true part here too (1c3cb2b) — same premature-exit issue on the git ls-remote pipeline, so it now reaches the validation block.
On sort -V: keeping it as-is. This repo already standardises on GNU sort -V in hack/download_openapi.sh and hack/init_version.sh (the former with a comment about prerelease ordering), and there's no macOS/BSD portability target, so matching the existing scripts keeps things consistent.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hack/update_versions.sh`:
- Around line 39-46: The argument parsing for `--dest`, `--branch`, and
`--cozystack-tag` options reads `$2` without checking if it exists, which causes
an unbound variable error when a flag is passed without a value. Add a guard
before each of these option handlers to check if `$2` is provided, and if not,
call the usage function and exit with an error status code. This applies to all
three options in the case statement that read the second argument
unconditionally.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: bdc30a93-015e-4bce-ba0f-99c632457e87
📒 Files selected for processing (11)
Makefilecontent/en/docs/next/install/talos/boot-to-talos.mdcontent/en/docs/v1.2/cozystack-api/go-types.mdcontent/en/docs/v1.3/install/talos/boot-to-talos.mdcontent/en/docs/v1.4/install/talos/boot-to-talos.mdcontent/en/docs/v1.5/install/talos/boot-to-talos.mddata/versions/next.yamldata/versions/v1.2.yamldata/versions/v1.5.yamlhack/release_next.shhack/update_versions.sh
| while [[ $# -gt 0 ]]; do | ||
| case "$1" in | ||
| --dest) DEST="$2"; shift 2 ;; | ||
| --branch) BRANCH="$2"; shift 2 ;; | ||
| --cozystack-tag) COZYSTACK_TAG="$2"; shift 2 ;; | ||
| -h|--help) usage; exit 0 ;; | ||
| *) echo "Unknown argument: $1" >&2; usage; exit 1 ;; | ||
| esac |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add missing option-value guards in CLI parsing.
--dest, --branch, and --cozystack-tag read $2 unconditionally. If a flag is passed without a value, set -u exits with an unbound-variable error instead of a controlled usage error.
💡 Suggested patch
while [[ $# -gt 0 ]]; do
case "$1" in
- --dest) DEST="$2"; shift 2 ;;
- --branch) BRANCH="$2"; shift 2 ;;
- --cozystack-tag) COZYSTACK_TAG="$2"; shift 2 ;;
+ --dest|--branch|--cozystack-tag)
+ if [[ $# -lt 2 ]]; then
+ echo "Error: $1 requires a value." >&2
+ usage
+ exit 1
+ fi
+ case "$1" in
+ --dest) DEST="$2" ;;
+ --branch) BRANCH="$2" ;;
+ --cozystack-tag) COZYSTACK_TAG="$2" ;;
+ esac
+ shift 2
+ ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown argument: $1" >&2; usage; exit 1 ;;
esac
done📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| while [[ $# -gt 0 ]]; do | |
| case "$1" in | |
| --dest) DEST="$2"; shift 2 ;; | |
| --branch) BRANCH="$2"; shift 2 ;; | |
| --cozystack-tag) COZYSTACK_TAG="$2"; shift 2 ;; | |
| -h|--help) usage; exit 0 ;; | |
| *) echo "Unknown argument: $1" >&2; usage; exit 1 ;; | |
| esac | |
| while [[ $# -gt 0 ]]; do | |
| case "$1" in | |
| --dest|--branch|--cozystack-tag) | |
| if [[ $# -lt 2 ]]; then | |
| echo "Error: $1 requires a value." >&2 | |
| usage | |
| exit 1 | |
| fi | |
| case "$1" in | |
| --dest) DEST="$2" ;; | |
| --branch) BRANCH="$2" ;; | |
| --cozystack-tag) COZYSTACK_TAG="$2" ;; | |
| esac | |
| shift 2 | |
| ;; | |
| -h|--help) usage; exit 0 ;; | |
| *) echo "Unknown argument: $1" >&2; usage; exit 1 ;; | |
| esac | |
| done |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hack/update_versions.sh` around lines 39 - 46, The argument parsing for
`--dest`, `--branch`, and `--cozystack-tag` options reads `$2` without checking
if it exists, which causes an unbound variable error when a flag is passed
without a value. Add a guard before each of these option handlers to check if
`$2` is provided, and if not, call the usage function and exit with an error
status code. This applies to all three options in the case statement that read
the second argument unconditionally.
Address review feedback from gemini-code-assist on hack/update_versions.sh:57: under `set -e`/`set -o pipefail` a failed curl pipeline made the command substitution exit the script before the validation block, so the helpful "could not read a Talos version" error never printed. Append `|| true` so the fetch failure falls through to the validation block instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
Address review feedback from gemini-code-assist on hack/update_versions.sh:70: same `set -e`/`pipefail` premature-exit issue on the `git ls-remote` pipeline. Append `|| true` so a failed lookup falls through to the validation block. The `sort -V` portability suggestion is intentionally not taken: the repo standardises on GNU `sort -V` (hack/download_openapi.sh, hack/init_version.sh), so this stays consistent with the existing scripts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
IvanHunters
left a comment
IvanHunters
left a comment
There was a problem hiding this comment.
Verdict
NOT LGTM — the fix for the stale-pin symptom is correct and well-scoped, but the new update-versions step introduces a release-pipeline regression that will fail every prerelease (-alpha/-beta/-rc.N) docs-update CI run from the upstream cozystack/cozystack tags workflow.
Findings
MAJOR
update-versionswill break the upstream tags workflow for every RC tag.- Upstream
.github/workflows/tags.yamlupdate-website-docsjob runsmake update-all BRANCH="release-$VERSION" RELEASE_TAG="$TAG"for every tag the regex^v\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$matches, including RCs (lines 456-540 of upstream tags.yaml). - For an RC like
v1.6.0-rc1, routing resolvesDOC_VERSION=next(nov1.6/yet), so the newupdate-versionsstep inMakefileruns and invokes./hack/update_versions.sh --branch v1.6.0-rc1 --cozystack-tag v1.6.0-rc1. hack/update_versions.sh:72enforces[[ "$COZYSTACK_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]], which rejects any prerelease suffix and exits 1.- Reproduction:
$ ./hack/update_versions.sh --dest /tmp/x.yaml --branch main --cozystack-tag v1.6.0-rc1 Error: could not determine a cozystack release tag (got 'v1.6.0-rc1'). exit: 1 - Pre-PR,
make update-all RELEASE_TAG=v1.6.0-rc1ran to completion; post-PR the docs-update CI job will fail and no PR will be opened againstcozystack/websitefor any RC. - Suggested fix (pick one):
- Gate
update-versionsin theMakefileonDOC_VERSION==next AND RELEASE_TAGbeing empty or a final-release tag. - OR loosen the regex in
update_versions.shto accept^v\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$and pin the prerelease tag verbatim. - OR, when an RC tag comes in, normalise it to the latest final release for the
cozystack_*keys but still refresh Talos keys against--branch.
- Gate
- Upstream
MINOR
data/versions/v1.2.yamland the PR description repeat an incorrect upstream-tag fact.- PR body: "the
api/apps/v1alpha1Go submodule's earliest tag isv1.2.0, so no earlier tag resolves forgo get." - Reality (verified via the Go module proxy):
api/apps/v1alpha1/v1.1.6andv1.1.7are real, resolvable Go-module versions. - The concrete action (keeping v1.0/v1.1 docs pinned to
@v1.2.0) still works, so the rendered docs are not broken. Butv1.2.yaml:11-14("the Go API submodule was first tagged atapi/apps/v1alpha1/v1.2.0") is factually wrong and will mislead the next person tidying this up. - Suggested fix: drop the "first tagged at" sentence, or reword to "v1.0/v1.1 keep
@v1.2.0as a deliberate forward-pin because no v1.0.x submodule tag exists and we choose not to backport this docs change to v1.1.7."
- PR body: "the
NITS
-
release_next.shsed rewrite drops inline comments fromcozystack_*lines. Existing files are untouched (theif [[ -e "$TARGET_DATA" ]]; then ... leaving it as-isguard), but every future snapshot will have terser comments than its predecessors. Purely cosmetic. -
Talos pin will drift silently between trunk-refreshes.
update-versionsonly runs whenDOC_VERSION=next, and there is no scheduled workflow that ever invokesmake update-allagainst trunk. Trunk freshness depends entirely on manual maintainer discipline. The release-timerelease_next.shsed rewrite only touchescozystack_version/cozystack_tag, leaving Talos values as-snapshotted. Risk: a long-untouchednext.yamlsnapshots a stale Talos intovX.Y.yamlat minor-cut time. Out of scope for this PR (explicitly deferred), but worth either a periodic GHA cron that runsmake update-versionsagainst trunk, or arelease_next.shstep that also re-runsupdate_versions.shagainst--branch $RELEASE_TAGbefore snapshotting.
What is good
- The core fix (replace
data/versions/v1.5.yamlandnext.yamlv1.3.0/v1.12.6 values with the correct v1.5.0/v1.13.0 values, verified againstcozystack/cozystack@v1.5.0/packages/core/talos/images/talos/profiles/installer.yaml) is exactly right. data/versions/v1.2.yamlschema matches sibling files; the v1.2go-types.mdshortcode call resolves correctly.- The boot-to-talos warning swap is consistent across
next/,v1.5/,v1.4/,v1.3/. On v1.3 the effective render is unchanged (literalv1.3.0/v1.12→ data lookup that also returnsv1.3.0/v1.12), so no regression on a previously-correct page. shellcheckclean on both new and modified shell scripts.release_next.shrewrite is idempotent and safe under the strict^vX.Y.Z$regex already enforced upstream of the sed.- The
update_versions.shfailure modes (network errors, missingversion:field, missing/empty tag list) all surface as exit-1 with a clear message, not silent stale output.
Claim alignment vs PR description
| # | Claim | Status |
|---|---|---|
| 3 | v1.0/v1.1 keep literal because api/apps/v1alpha1 earliest tag is v1.2.0 |
PARTIAL — earliest tag is v1.1.6; action still works but rationale and v1.2.yaml comment are factually wrong (see Finding 2). |
| 5 | update_versions.sh + make update-versions in update-all |
PARTIAL — wired in, but breaks for any RC tag in the upstream release pipeline (see Finding 1). |
Claims 1, 2, 4, 6, 7, 8, 9 — OK (verified).
Suggested merge plan
Block on Finding 1 — either gate update-versions in the Makefile, or loosen the regex in update_versions.sh. Either is a small follow-up commit. Findings 2-4 can land as separate touch-ups without blocking this one.
2 participants
What & why
The
{{< version-pin >}}data file for the default docs version (data/versions/v1.5.yaml) was a verbatim copy ofnext.yamlthat never got bumped, so every version-pin on the v1.5 docs rendered cozystackv1.3.0/ Talosv1.12.6instead ofv1.5.0/v1.13.0— including the Go typesgo getexample and ~40 install-doc references. Root cause:release_next.shsnapshotsnext.yaml, andnext.yamlhad itself been stale since the v1.3 cycle.Changes
Correct the stale pins
data/versions/v1.5.yamlto the real v1.5 values (v1.5.0/ Talosv1.13.0, verified against the upstream v1.5.0 installer profile).data/versions/v1.2.yamland switch the v1.2go-typespage from a hardcoded@v1.2.0toversion-pin. v1.0/v1.1 keep the literal — theapi/apps/v1alpha1Go submodule's earliest tag isv1.2.0, so no earlier tag resolves forgo get.Stop it recurring
release_next.shto rewritecozystack_version/cozystack_tagfromRELEASE_TAGat snapshot time, so a stalenext.yamlcan't freeze the wrong version into a release again.hack/update_versions.sh+ amake update-versionsstep inupdate-allthat regeneratesnext.yamlfrom upstream (Talos from the installer profile, cozystack tag from the latest release). The next trunk can no longer go stale; regeneration is idempotent.Fix a rendered-wrong warning
boot-to-talosversion-mismatch warning hardcoded "Cozystack v1.3.0 … target Talos v1.12", which rendered wrong on v1.4/v1.5 (both ship Talos v1.13). Swap the literals for theversion-pinshortcodes already used elsewhere in the same file, across next/v1.5/v1.4/v1.3.Not included (flagged for follow-up)
source:URLs innext/are frozen atv1.3.0(should trackmain). They self-heal on the nextmake update-allfor the trunk and that also refetches README bodies, so it's better done as a separate, deliberate re-sync.Test notes
v1.5.0/ Talosv1.13; v1.3 unchanged / correct).hack/update_versions.shis byte-idempotent across consecutive runs;release_next.shsnapshot rewrite verified in isolation.hugobuild was not run here — local Hugo is v0.163.0 vs the repo-pinned v0.160.1, and 0.163'ssecurity.allowContentpolicy rejects an unrelated existing content file. CI/Netlify use the pinned version.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores