fix(docs): correct stale version pins and prevent next.yaml drift#589
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. |
📝 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 docstrings
🧪 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
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.
Address review feedback from coderabbitai on hack/update_versions.sh:46:
--dest/--branch/--cozystack-tag now emit a clear usage error instead of
tripping set -u ("unbound variable") when a flag is passed without a value.
Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
Address review feedback from IvanHunters on the Makefile: the upstream cozystack/cozystack tags workflow runs `make update-all` for every -rc/-beta/-alpha tag too, but update_versions.sh only accepts final vX.Y.Z tags. Gate the step on a non-prerelease RELEASE_TAG so prerelease docs-update CI runs no longer fail; trunk pins keep tracking the latest final release. Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
Address review feedback from IvanHunters on data/versions/v1.2.yaml: earlier git tags api/apps/v1alpha1/v1.1.6 and v1.1.7 exist but do not resolve as Go module versions (proxy.golang.org returns 404), whereas v1.2.0 resolves. So v1.2.0 is the earliest `go get`-resolvable version; the action is unchanged and only the rationale comment is corrected. Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
|
IvanHunters Thanks for the thorough review — addressed point by point. MAJOR 1 (RC pipeline regression): Confirmed. The upstream MINOR 2 (go-module tag fact): You're right the "first tagged at v1.2.0" wording was wrong — the NIT 3 (release_next.sh sed drops comments): Leaving as-is — as you noted it's purely cosmetic and existing files are protected by the NIT 4 (Talos pin drift on the trunk): Agreed it's a real gap, but out of scope for this PR as flagged. The MAJOR fix keeps trunk Talos refresh on plain |
IvanHunters
left a comment
IvanHunters
left a comment
There was a problem hiding this comment.
Verdict
LGTM with non-blocking notes.
Diff addresses the root cause on four fronts — corrects the stale v1.5 data file, hardens the release script so a stale next.yaml cannot poison the next snapshot, adds drift-prevention regeneration tooling, and replaces hardcoded version literals in the boot-to-talos warning with the version-pin shortcode. New v1.5 values match the upstream v1.5.0 installer profile (version: v1.13.0).
Findings
[MINOR] hack/release_next.sh:138-139 — snapshot sed strips inline YAML comments
The two sed expressions use .* after the capture group, which eats the trailing inline comment along with the old value:
sed -i.bak \
-e "s|^\(cozystack_version:[[:space:]]*\).*|\1\"${VERSION_BARE}\"|" \
-e "s|^\(cozystack_tag:[[:space:]]*\).*|\1\"${RELEASE_TAG}\"|" \
"$TARGET_DATA"update_versions.sh writes the trunk with inline annotations:
cozystack_version: "1.5.0" # bare, as used by `helm --version`
cozystack_tag: "v1.5.0" # v-prefixed, as used in GitHub URLsAfter the snapshot, the released vX.Y.yaml loses both annotations, while hand-pinned files like data/versions/v1.3.yaml / v1.4.yaml still carry them. The frozen file ends up with a slightly different shape than its siblings, and an operator inspecting the file later loses the "bare vs v-prefixed" hint that explains why two near-identical keys exist.
Suggested fix: anchor the replacement on the quoted value rather than the rest of the line, e.g. s|\(cozystack_version:[[:space:]]*\)"[^"]*"|\1"${VERSION_BARE}"| — preserves the trailing comment and any whitespace alignment.
Claim mismatches
None — every claim in the PR body that could be verified was verified:
data/versions/v1.5.yamlTalosv1.13.0matchescozystack/cozystack@v1.5.0:packages/core/talos/images/talos/profiles/installer.yamlversion: v1.13.0(re-fetched directly).update_versions.shis byte-idempotent across consecutive runs (no time-dependent or random content in the heredoc; output deterministic from--branchand--cozystack-tag).release_next.sh:57validatesRELEASE_TAGas^v([0-9]+)\.([0-9]+)\.([0-9]+)$before the sed runs, so RELEASE_TAG cannot inject sed metacharacters.- Pre-release skipping is wired in two places that agree:
Makefile:27(_is_prerelease := $(findstring -,$(RELEASE_TAG))) gates the make target;update_versions.sh:73enforces^v[0-9]+\.[0-9]+\.[0-9]+$on the resolved tag.
Red-team concerns
- Upstream tag must exist before docs update. When
make update-all RELEASE_TAG=vX.Y.Zruns for a new minor cut, BRANCH is overridden toRELEASE_TAG(Makefile:22), soupdate_versions.shcurlshttps://raw.githubusercontent.com/cozystack/cozystack/${RELEASE_TAG}/packages/core/talos/images/talos/profiles/installer.yaml. If the release workflow runs the docs job before pushing the upstream tag, curl returns 404 and the script exits cleanly with "could not read a Talos version" — no silent corruption, but the docs job hard-fails. This isn't a defect of this PR (it's an ordering constraint on the release flow), but the constraint is now load-bearing and undocumented. Worth a one-liner inhack/release-checklist.mdor the script header. - Transient GitHub failures break update-all.
curl -fsSLhas no retry;git ls-remotehas no retry. A rate-limit or 5xx mid-update aborts the trunk regeneration. Acceptable for now since make is re-runnable, but a--retries Ncurl flag would shorten the failure tail.
Caveats
- This is the Hugo docs repo (
cozystack/website), notcozystack/cozystack. The cozystack monorepo invariants (cozyrds drift, migrations.targetVersion, RBAC patterns) do not apply here. The repo-specific contractversion-pinresolves was verified atlayouts/shortcodes/version-pin.html— keys missing fromdata/versions/<version>.yamlfail the Hugo build, so the v1.2 file addition is required for the new go-types pin to render. - The 25 autogenerated
source:URLs innext/frozen atv1.3.0are deferred per PR body. Confirmed they sit incontent/en/docs/next/and not inv1.5/, so the released v1.5 docs are not affected. Worth a follow-up issue so it does not slip. - A full
hugobuild was not performed in this review (local Hugo would require matching the repo-pinned 0.160.1); shortcode resolution was verified by readinglayouts/shortcodes/version-pin.htmldirectly. The PR's own test notes acknowledge the same limitation.
Recommended follow-ups
- Separate PR to re-sync the 25
source:URLs innext/by re-runningmake update-allon the trunk. - Document the "upstream tag must exist before docs
update-all RELEASE_TAG=…" ordering constraint inhack/release-checklist.md(or as a comment block inupdate_versions.sh).
|
Thanks for the detailed point-by-point — re-reviewed against the new HEAD and the fixes hold up:
On the |
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/v1alpha1submodule has earlier git tags (v1.1.6,v1.1.7) but they don't resolve as Go modules (proxy.golang.org404s), sov1.2.0is the earliest versiongo getresolves.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