fix(docs): correct stale version pins and prevent next.yaml drift (#589)

myasnikovdaniil · web-flow · commit 0c52332ffabc · 2026-06-26T12:29:52.000+05:00
## What & why The `{{< version-pin >}}` data file for the default docs version (`data/versions/v1.5.yaml`) was a verbatim copy of `next.yaml` that never got bumped, so **every** version-pin on the v1.5 docs rendered cozystack `v1.3.0` / Talos `v1.12.6` instead of `v1.5.0` / `v1.13.0` — including the Go types `go get` example and ~40 install-doc references. Root cause: `release_next.sh` snapshots `next.yaml`, and `next.yaml` had itself been stale since the v1.3 cycle. ## Changes **Correct the stale pins** - Fix `data/versions/v1.5.yaml` to the real v1.5 values (`v1.5.0` / Talos `v1.13.0`, verified against the upstream v1.5.0 installer profile). - Add `data/versions/v1.2.yaml` and switch the v1.2 `go-types` page from a hardcoded `@v1.2.0` to `version-pin`. v1.0/v1.1 keep the literal — the `api/apps/v1alpha1` submodule has earlier git tags (`v1.1.6`, `v1.1.7`) but they don't resolve as Go modules (`proxy.golang.org` 404s), so `v1.2.0` is the earliest version `go get` resolves. **Stop it recurring** - Harden `release_next.sh` to rewrite `cozystack_version`/`cozystack_tag` from `RELEASE_TAG` at snapshot time, so a stale `next.yaml` can't freeze the wrong version into a release again. - Add `hack/update_versions.sh` + a `make update-versions` step in `update-all` that regenerates `next.yaml` from 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** - The `boot-to-talos` version-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 the `version-pin` shortcodes already used elsewhere in the same file, across next/v1.5/v1.4/v1.3. ## Not included (flagged for follow-up) - 25 autogenerated `source:` URLs in `next/` are frozen at `v1.3.0` (should track `main`). They self-heal on the next `make update-all` for the trunk and that also refetches README bodies, so it's better done as a separate, deliberate re-sync. ## Test notes - Verified each affected page's effective render against its data file (v1.5 → `v1.5.0` / Talos `v1.13`; v1.3 unchanged / correct). - `hack/update_versions.sh` is byte-idempotent across consecutive runs; `release_next.sh` snapshot rewrite verified in isolation. - A full `hugo` build was not run here — local Hugo is v0.163.0 vs the repo-pinned v0.160.1, and 0.163's `security.allowContent` policy rejects an unrelated existing content file. CI/Netlify use the pinned version. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **Documentation** * Updated Talos installation guides to use generic, version-pinned compatibility warnings (using template-driven Cozystack/Talos pins) instead of hardcoded examples. * Updated Go API installation instructions to use dynamic version pins rather than a fixed version tag. * **Chores** * Added automated version-data regeneration tooling for documentation pins, including prerelease handling and safer “next” updates. * Regenerated next/trunk and updated released pins (Cozystack v1.5.0; Talos v1.13.0), including improved release snapshot pinning.
diff --git a/Makefile b/Makefile
@@ -23,6 +23,11 @@ else
   BRANCH ?= main
 endif
 
+# Non-empty when RELEASE_TAG carries a prerelease suffix (-rc.N / -beta.N /
+# -alpha.N). Used to skip trunk pin regeneration on prereleases — update_versions.sh
+# only accepts final vX.Y.Z tags, and the trunk should track the latest final release.
+_is_prerelease := $(findstring -,$(RELEASE_TAG))
+
 # Routing: DOC_VERSION is either a real vX.Y directory (patch releases of an
 # already-released version) or `next` (everything else).
 #
@@ -74,6 +79,7 @@ NETWORKING_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/networking
 SERVICES_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/operations/services
 
 .PHONY: update-apps update-vms update-networking update-k8s update-services update-oss-health update-all \
+        update-versions \
         template-apps template-vms template-networking template-k8s template-services template-all \
         init-version init-next release-next download-openapi download-openapi-all serve show-target
 
@@ -144,6 +150,25 @@ update-all:
 	$(MAKE) update-networking
 	$(MAKE) update-k8s
 	$(MAKE) update-services
+	$(MAKE) update-versions
+
+# Regenerate the {{< version-pin >}} data file from upstream so the next/ trunk
+# never goes stale. Only the next trunk is auto-managed here; released vX.Y.yaml
+# files are frozen at release time by hack/release_next.sh.
+#
+# Prerelease tags are skipped: the upstream tags workflow runs `make update-all`
+# for every -rc/-beta/-alpha tag too, but update_versions.sh only accepts final
+# vX.Y.Z tags, and the trunk pins are meant to track the latest final release.
+update-versions:
+ifeq ($(DOC_VERSION),next)
+ifeq ($(_is_prerelease),)
+	./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(BRANCH)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
+else
+	@echo "update-versions: prerelease $(RELEASE_TAG) — skipping trunk pin refresh (pins track the latest final release)."
+endif
+else
+	@echo "update-versions: $(DOC_VERSION) is a released version (frozen at release time) — skipping."
+endif
 
 template-apps:
 	./hack/fill_templates.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)"
diff --git a/content/en/docs/next/install/talos/boot-to-talos.md b/content/en/docs/next/install/talos/boot-to-talos.md
@@ -32,11 +32,7 @@ Use `ghcr.io/cozystack/cozystack/talos:{{< version-pin "talos" >}}` as the `boot
 `boot-to-talos` v0.7.x carries its own hardcoded default image
 (`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see
 [`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)).
-If you let the interactive prompt fall through to that default on a cluster
-you intend to run Cozystack v1.3.0, you will end up with a Talos v1.11 node
-while the Cozystack installer and Talm templates target Talos v1.12 — you
-will hit a mismatch at bootstrap time. Always type in the image matching
-your target Cozystack release (or pass `-image` on the command line).
+If you let the interactive prompt fall through to that default on a cluster you intend to run Cozystack {{< version-pin "cozystack_version" >}}, you will end up with a Talos v1.11 node while the Cozystack installer and Talm templates target Talos {{< version-pin "talos_minor" >}} — you will hit a mismatch at bootstrap time. Always type in the image matching your target Cozystack release (or pass `-image` on the command line).
 {{% /alert %}}
 
 ## Modes
diff --git a/content/en/docs/v1.2/cozystack-api/go-types.md b/content/en/docs/v1.2/cozystack-api/go-types.md
@@ -13,7 +13,7 @@ Cozystack publishes its Kubernetes resource types as a Go module, enabling manag
 Add the dependency to your Go module:
 
 ```bash
-go get github.com/cozystack/cozystack/api/apps/v1alpha1@v1.2.0
+go get github.com/cozystack/cozystack/api/apps/v1alpha1@{{< version-pin "cozystack_tag" >}}
 ```
 
 ## Use Cases
diff --git a/content/en/docs/v1.3/install/talos/boot-to-talos.md b/content/en/docs/v1.3/install/talos/boot-to-talos.md
@@ -32,11 +32,7 @@ Use `ghcr.io/cozystack/cozystack/talos:{{< version-pin "talos" >}}` as the `boot
 `boot-to-talos` v0.7.x carries its own hardcoded default image
 (`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see
 [`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)).
-If you let the interactive prompt fall through to that default on a cluster
-you intend to run Cozystack v1.3.0, you will end up with a Talos v1.11 node
-while the Cozystack installer and Talm templates target Talos v1.12 — you
-will hit a mismatch at bootstrap time. Always type in the image matching
-your target Cozystack release (or pass `-image` on the command line).
+If you let the interactive prompt fall through to that default on a cluster you intend to run Cozystack {{< version-pin "cozystack_version" >}}, you will end up with a Talos v1.11 node while the Cozystack installer and Talm templates target Talos {{< version-pin "talos_minor" >}} — you will hit a mismatch at bootstrap time. Always type in the image matching your target Cozystack release (or pass `-image` on the command line).
 {{% /alert %}}
 
 ## Modes
diff --git a/content/en/docs/v1.4/install/talos/boot-to-talos.md b/content/en/docs/v1.4/install/talos/boot-to-talos.md
@@ -32,11 +32,7 @@ Use `ghcr.io/cozystack/cozystack/talos:{{< version-pin "talos" >}}` as the `boot
 `boot-to-talos` v0.7.x carries its own hardcoded default image
 (`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see
 [`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)).
-If you let the interactive prompt fall through to that default on a cluster
-you intend to run Cozystack v1.3.0, you will end up with a Talos v1.11 node
-while the Cozystack installer and Talm templates target Talos v1.12 — you
-will hit a mismatch at bootstrap time. Always type in the image matching
-your target Cozystack release (or pass `-image` on the command line).
+If you let the interactive prompt fall through to that default on a cluster you intend to run Cozystack {{< version-pin "cozystack_version" >}}, you will end up with a Talos v1.11 node while the Cozystack installer and Talm templates target Talos {{< version-pin "talos_minor" >}} — you will hit a mismatch at bootstrap time. Always type in the image matching your target Cozystack release (or pass `-image` on the command line).
 {{% /alert %}}
 
 ## Modes
diff --git a/content/en/docs/v1.5/install/talos/boot-to-talos.md b/content/en/docs/v1.5/install/talos/boot-to-talos.md
@@ -32,11 +32,7 @@ Use `ghcr.io/cozystack/cozystack/talos:{{< version-pin "talos" >}}` as the `boot
 `boot-to-talos` v0.7.x carries its own hardcoded default image
 (`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see
 [`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)).
-If you let the interactive prompt fall through to that default on a cluster
-you intend to run Cozystack v1.3.0, you will end up with a Talos v1.11 node
-while the Cozystack installer and Talm templates target Talos v1.12 — you
-will hit a mismatch at bootstrap time. Always type in the image matching
-your target Cozystack release (or pass `-image` on the command line).
+If you let the interactive prompt fall through to that default on a cluster you intend to run Cozystack {{< version-pin "cozystack_version" >}}, you will end up with a Talos v1.11 node while the Cozystack installer and Talm templates target Talos {{< version-pin "talos_minor" >}} — you will hit a mismatch at bootstrap time. Always type in the image matching your target Cozystack release (or pass `-image` on the command line).
 {{% /alert %}}
 
 ## Modes
diff --git a/data/versions/next.yaml b/data/versions/next.yaml
@@ -1,21 +1,18 @@
-# Pinned upstream-tool versions for the `next/` trunk docs.
+# AUTOGENERATED by hack/update_versions.sh — do not edit by hand.
 #
-# Referenced from content via the {{< version-pin "<key>" >}} shortcode. See
-# data/versions/v1.3.yaml for key semantics and rationale.
+# Regenerated by 'make update-all' so the {{< version-pin >}} values in the
+# next/ trunk track upstream cozystack/cozystack@main:
 #
-# During development of an upcoming release, keep these values pointing at the
-# latest upstream pre-release / pinned versions for the forthcoming minor so
-# the `next/` docs render deterministically. At release time,
-# hack/release_next.sh copies this file to data/versions/v<major>.<minor>.yaml
-# so the released docs freeze on the values that were true at the cut.
+#   talos / talos_minor       ← packages/core/talos/images/talos/profiles/installer.yaml @ main
+#   cozystack_version / _tag   ← latest final release tag (the upcoming release's
+#                                own tag/assets don't exist until it is cut;
+#                                hack/release_next.sh overrides these from
+#                                RELEASE_TAG when next/ is promoted).
 
-# Upcoming Cozystack release the trunk targets.
-# Use the target tag while the minor is in development (e.g. "v1.4.0").
-cozystack_version: "1.3.0"
-cozystack_tag:     "v1.3.0"
+# Cozystack release the docs are pinned to.
+cozystack_version: "1.5.0"   # bare, as used by `helm --version`
+cozystack_tag:     "v1.5.0"  # v-prefixed, as used in GitHub URLs
 
-# Talos version shipped by the Cozystack installer for the upcoming minor.
-# Keep in sync with packages/core/talos/images/talos/profiles/installer.yaml
-# in cozystack/cozystack on main.
-talos:       "v1.12.6"
-talos_minor: "v1.12"
+# Talos version shipped by the Cozystack installer for this trunk.
+talos:       "v1.13.0"
+talos_minor: "v1.13"           # the docs minor used by talos.dev URLs
diff --git a/data/versions/v1.2.yaml b/data/versions/v1.2.yaml
@@ -0,0 +1,20 @@
+# Pinned upstream-tool versions for the Cozystack v1.2 docs.
+#
+# Referenced from content via the {{< version-pin "<key>" >}} shortcode, which
+# derives the version directory from the page's file path — a page under
+# content/en/docs/v1.2/ reads this file.
+#
+# Minimal by design: only the keys actually referenced by v1.2 pages are
+# present (see v0.yaml for the same philosophy). The single consumer is
+# cozystack-api/go-types.md.
+#
+# Note: the Go API submodule (github.com/cozystack/cozystack/api/apps/v1alpha1)
+# has earlier git tags (api/apps/v1alpha1/v1.1.6, v1.1.7), but those do not
+# resolve as Go module versions — proxy.golang.org returns 404 for them, while
+# v1.2.0 resolves. So v1.2.0 is the earliest version `go get` can fetch, making
+# v1.2 the first release whose go-types page can pin to its own tag. The
+# v1.0/v1.1 go-types pages keep a v1.2.0 literal for the same reason: no earlier
+# resolvable module version exists.
+
+# Cozystack release the docs are pinned to.
+cozystack_tag: "v1.2.0"        # v-prefixed, as used in `go get …@<tag>`
diff --git a/data/versions/v1.5.yaml b/data/versions/v1.5.yaml
@@ -1,21 +1,23 @@
-# Pinned upstream-tool versions for the `next/` trunk docs.
+# Pinned upstream-tool versions for the Cozystack v1.5 docs.
 #
-# Referenced from content via the {{< version-pin "<key>" >}} shortcode. See
-# data/versions/v1.3.yaml for key semantics and rationale.
+# Referenced from content via the {{< version-pin "<key>" >}} shortcode. The
+# shortcode derives the version directory from the page's file path, so a page
+# under content/en/docs/v1.5/ reads this file.
 #
-# During development of an upcoming release, keep these values pointing at the
-# latest upstream pre-release / pinned versions for the forthcoming minor so
-# the `next/` docs render deterministically. At release time,
-# hack/release_next.sh copies this file to data/versions/v<major>.<minor>.yaml
-# so the released docs freeze on the values that were true at the cut.
+# Only include pins that are coupled to the Cozystack release and would go
+# stale if not updated — the Talos tag that ships in the installer, Cozystack
+# release-asset URLs, and tagged source-tree links. Tools that stay
+# backwards-compatible across minors (talm, boot-to-talos, talos-bootstrap
+# install scripts) stay floating on main / latest in the markdown.
+#
+# Update when cutting a new minor (see hack/release-checklist.md).
 
-# Upcoming Cozystack release the trunk targets.
-# Use the target tag while the minor is in development (e.g. "v1.4.0").
-cozystack_version: "1.3.0"
-cozystack_tag:     "v1.3.0"
+# Cozystack release the docs are pinned to.
+cozystack_version: "1.5.0"     # bare, as used by `helm --version`
+cozystack_tag:     "v1.5.0"    # v-prefixed, as used in GitHub URLs
 
-# Talos version shipped by the Cozystack installer for the upcoming minor.
-# Keep in sync with packages/core/talos/images/talos/profiles/installer.yaml
-# in cozystack/cozystack on main.
-talos:       "v1.12.6"
-talos_minor: "v1.12"
+# Talos version shipped by the Cozystack installer for this minor.
+# Source of truth: packages/core/talos/images/talos/profiles/installer.yaml
+# in the cozystack/cozystack repo at `cozystack_tag`.
+talos:       "v1.13.0"
+talos_minor: "v1.13"           # the docs minor used by talos.dev URLs
diff --git a/hack/release_next.sh b/hack/release_next.sh
@@ -131,7 +131,17 @@ if [[ -f "$NEXT_DATA" ]]; then
     echo "! $TARGET_DATA already exists; leaving it as-is." >&2
   else
     cp "$NEXT_DATA" "$TARGET_DATA"
-    echo "✓ Snapshotted $NEXT_DATA → $TARGET_DATA"
+    # Pin the release-coupled Cozystack version from RELEASE_TAG so a stale
+    # next.yaml can't silently freeze the wrong version into the snapshot —
+    # this is exactly how v1.5.yaml once inherited next.yaml's v1.3.0 values.
+    # Talos pins are left as snapshotted; they're refreshed manually per cycle.
+    VERSION_BARE="${RELEASE_TAG#v}"
+    sed -i.bak \
+      -e "s|^\(cozystack_version:[[:space:]]*\).*|\1\"${VERSION_BARE}\"|" \
+      -e "s|^\(cozystack_tag:[[:space:]]*\).*|\1\"${RELEASE_TAG}\"|" \
+      "$TARGET_DATA"
+    rm -f "$TARGET_DATA.bak"
+    echo "✓ Snapshotted $NEXT_DATA → $TARGET_DATA (pinned cozystack_tag=${RELEASE_TAG})"
   fi
 else
   echo "! $NEXT_DATA missing; skipped data/versions snapshot. Create $TARGET_DATA manually if the docs use {{< version-pin >}}." >&2
diff --git a/hack/update_versions.sh b/hack/update_versions.sh
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: hack/update_versions.sh [OPTIONS]
+
+Regenerate a data/versions/<version>.yaml pin file from upstream
+cozystack/cozystack, so the {{< version-pin >}} values never go stale.
+
+Sources of truth:
+  * talos / talos_minor     ← packages/core/talos/images/talos/profiles/installer.yaml
+                              at --branch (always the version main/the tag ships).
+  * cozystack_version/_tag  ← --cozystack-tag if given (e.g. an upcoming release
+                              tag); otherwise the latest final upstream release
+                              tag. Used as the `next` trunk's resolvable default
+                              until the real release is cut.
+
+Options:
+  --dest PATH           data/versions/<version>.yaml file to (re)generate (required)
+  --branch REF          Git ref in cozystack/cozystack to read the Talos installer
+                        from (default: main)
+  --cozystack-tag TAG   Pin cozystack_tag to this vX.Y.Z tag instead of the latest
+                        release (optional)
+  -h, --help            Show this help and exit
+
+Examples:
+  hack/update_versions.sh --dest data/versions/next.yaml --branch main
+  hack/update_versions.sh --dest data/versions/next.yaml --branch v1.6.0 --cozystack-tag v1.6.0
+EOF
+}
+
+SOURCE_REPO="cozystack/cozystack"
+DEST=""
+BRANCH="main"
+COZYSTACK_TAG=""
+
+# -------------------- Parse arguments --------------------
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dest|--branch|--cozystack-tag)
+      # Guard the value-taking flags: without this, a missing value makes the
+      # `$2` read trip `set -u` ("unbound variable") instead of a clean usage error.
+      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
+
+if [[ -z "$DEST" ]]; then
+  echo "Error: --dest is required." >&2
+  usage; exit 1
+fi
+
+# -------------------- 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}' || true)"
+if [[ ! "$talos" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Error: could not read a Talos version from $INSTALLER_URL (got '${talos:-}')." >&2
+  exit 1
+fi
+talos_minor="${talos%.*}"   # v1.13.0 -> v1.13
+
+# -------------------- 2. Cozystack release tag --------------------
+if [[ -z "$COZYSTACK_TAG" ]]; then
+  # Latest final release: top-level refs/tags/vX.Y.Z only (excludes the
+  # api/apps/v1alpha1/* submodule tags and any -rc/-beta pre-releases).
+  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 || true)"
+fi
+if [[ ! "$COZYSTACK_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Error: could not determine a cozystack release tag (got '${COZYSTACK_TAG:-}')." >&2
+  exit 1
+fi
+cozystack_version="${COZYSTACK_TAG#v}"
+
+# -------------------- 3. (Re)generate the pin file --------------------
+mkdir -p "$(dirname "$DEST")"
+cat > "$DEST" <<EOF
+# AUTOGENERATED by hack/update_versions.sh — do not edit by hand.
+#
+# Regenerated by 'make update-all' so the {{< version-pin >}} values in the
+# next/ trunk track upstream cozystack/cozystack@${BRANCH}:
+#
+#   talos / talos_minor       ← ${INSTALLER_PATH} @ ${BRANCH}
+#   cozystack_version / _tag   ← latest final release tag (the upcoming release's
+#                                own tag/assets don't exist until it is cut;
+#                                hack/release_next.sh overrides these from
+#                                RELEASE_TAG when next/ is promoted).
+
+# Cozystack release the docs are pinned to.
+cozystack_version: "${cozystack_version}"   # bare, as used by \`helm --version\`
+cozystack_tag:     "${COZYSTACK_TAG}"  # v-prefixed, as used in GitHub URLs
+
+# Talos version shipped by the Cozystack installer for this trunk.
+talos:       "${talos}"
+talos_minor: "${talos_minor}"           # the docs minor used by talos.dev URLs
+EOF
+
+echo "✓ Regenerated $DEST (cozystack_tag=${COZYSTACK_TAG}, talos=${talos}, from ${SOURCE_REPO}@${BRANCH})"
