docs: update the upgrade talos version make target

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>

Author: Iheanacho-ai

Makefile

@@ -16,6 +16,14 @@ TALOS_VERSION := v1.14
 VALE_IMAGE := jdkato/vale:latest
 VALE_CONFIG ?= .vale.ini
 
+# Auto-fill the GitHub token from `gh` when it isn't already set in the environment.
+# An exported/CI value wins; otherwise fall back to the local gh keychain. If gh is
+# unavailable this is simply empty, matching the previous behaviour.
+# `export` makes it visible to recipe subprocesses (e.g. the local `go run` targets),
+# not just to the containers that pass it explicitly with `-e`.
+GITHUB_TOKEN ?= $(shell gh auth token 2>/dev/null)
+export GITHUB_TOKEN
+
 # Default target
 .PHONY: help
 help: ## Show this help message
@@ -131,13 +139,19 @@ test-docs-gen-race: ## Run tests with race detection
 .PHONY: test-all
 test-all: test-docs-gen ## Run all tests
 
+# talosctl is a multi-arch image and its `--arch` flag defaults to the running
+# binary's architecture (runtime.GOARCH). Pin the platform so the generated
+# reference docs are deterministic (matching CI) regardless of the contributor's
+# machine — otherwise regenerating on Apple Silicon flips defaults to arm64.
+TALOSCTL_PLATFORM := linux/amd64
+
 .PHONY: generate-talos-reference
 generate-talos-reference: ## Generate Talos reference docs and convert to MDX
 	@echo "Generating Talos reference documentation..."
-	docker pull $(TALOSCTL_IMAGE)
+	docker pull --platform=$(TALOSCTL_PLATFORM) $(TALOSCTL_IMAGE)
 	docker pull $(DOCS_CONVERT_IMAGE)
 	mkdir -p _out/docs
-	docker run --rm -u $(shell id -u):$(shell id -g) -v $(PWD)/_out/docs:/docs $(TALOSCTL_IMAGE) docs /docs
+	docker run --rm --platform=$(TALOSCTL_PLATFORM) -u $(shell id -u):$(shell id -g) -v $(PWD)/_out/docs:/docs $(TALOSCTL_IMAGE) docs /docs
 	@echo "Converting generated docs to MDX..."
 	docker run --rm -u $(shell id -u):$(shell id -g) -v $(PWD):/workspace $(DOCS_CONVERT_IMAGE) \
 		/workspace/_out/docs /workspace/public/talos/$(TALOS_VERSION)/reference/configuration/
@@ -147,9 +161,9 @@ generate-talos-reference: ## Generate Talos reference docs and convert to MDX
 .PHONY: generate-talos-reference-local
 generate-talos-reference-local: ## Generate Talos reference docs using local Go build
 	@echo "Generating Talos reference documentation..."
-	docker pull $(TALOSCTL_IMAGE)
+	docker pull --platform=$(TALOSCTL_PLATFORM) $(TALOSCTL_IMAGE)
 	mkdir -p _out/docs
-	docker run --rm -u $(shell id -u):$(shell id -g) -v $(PWD)/_out/docs:/docs $(TALOSCTL_IMAGE) docs /docs
+	docker run --rm --platform=$(TALOSCTL_PLATFORM) -u $(shell id -u):$(shell id -g) -v $(PWD)/_out/docs:/docs $(TALOSCTL_IMAGE) docs /docs
 	@echo "Converting generated docs to MDX..."
 	cd docs-convert && go run main.go ../_out/docs ../public/talos/$(TALOS_VERSION)/reference/configuration/
 	@echo "Reference documentation generated in public/talos/$(TALOS_VERSION)/reference/configuration/"
@@ -331,29 +345,53 @@ changelog-local: ## Generate the changelog using local Go build
 validate-docs-nav: ## Validate all talos yaml nav configs match their content directories
 	cd docs-validate && go run . --workspace ..
 
+# validate-tag distinguishes the two ways a TAG can be wrong, with a tailored
+# message for each, and fails BEFORE the generator writes anything:
+#   1. malformed  -> show the expected format and examples
+#   2. unpublished -> the format is fine but no talosctl image exists for it yet
+define validate-tag
+	@echo "$(TAG)" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$$' || { \
+		echo "Error: malformed TAG '$(TAG)'."; \
+		echo "  Expected: vMAJOR.MINOR.PATCH with an optional -alpha.N / -beta.N / -rc.N suffix."; \
+		echo "  Examples: v1.14.0   v1.14.0-alpha.0   v1.14.0-beta.2   v1.14.0-rc.1"; \
+		exit 1; }
+	@docker manifest inspect ghcr.io/siderolabs/talosctl:$(TAG) >/dev/null 2>&1 || { \
+		echo "Error: TAG '$(TAG)' is well-formed but not published yet."; \
+		echo "  No image 'ghcr.io/siderolabs/talosctl:$(TAG)' was found in the registry."; \
+		echo "  The release may not be cut yet — see https://github.com/siderolabs/talos/releases"; \
+		echo "  Pass a TAG whose talosctl image already exists."; \
+		exit 1; }
+endef
+
 .PHONY: upgrade-talos-version
-upgrade-talos-version: ## Upgrade docs to the next Talos minor version (fetches versions from GitHub)
+upgrade-talos-version: ## Upgrade Talos docs to a release tag: make upgrade-talos-version TAG=v1.14.0-beta.0
+	@test -n "$(TAG)" || { echo "Error: TAG is required, e.g. make upgrade-talos-version TAG=v1.14.0-beta.0"; exit 1; }
+	$(validate-tag)
 	docker run --rm -it -v $(PWD):/workspace -w /workspace \
 		-e GITHUB_TOKEN=$(GITHUB_TOKEN) \
-		$(VERSION_UPGRADE_IMAGE)
-	$(eval NEW_VERSION := $(shell cat .upgrade-version-tmp))
+		$(VERSION_UPGRADE_IMAGE) --tag $(TAG)
+	$(eval NEW_VERSION := $(shell cat .upgrade-version-tmp 2>/dev/null))
 	@rm -f .upgrade-version-tmp
+	$(MAKE) generate-talos-reference
 	$(MAKE) changelog
 	$(MAKE) docs.json
 	$(MAKE) validate-docs-nav
 	@echo ""
-	@echo "Upgrade to $(NEW_VERSION) complete! Run: make preview to preview your $(NEW_VERSION) docs"
+	@echo "Upgrade to $(TAG) complete! Run: make preview to preview your $(NEW_VERSION) docs"
 
 .PHONY: upgrade-talos-version-local
-upgrade-talos-version-local: ## Upgrade docs to the next Talos minor version using local Go build
-	cd version-upgrade-gen && go run . --workspace ..
-	$(eval NEW_VERSION := $(shell cat .upgrade-version-tmp))
+upgrade-talos-version-local: ## Same as upgrade-talos-version but using the local Go build
+	@test -n "$(TAG)" || { echo "Error: TAG is required, e.g. make upgrade-talos-version-local TAG=v1.14.0-beta.0"; exit 1; }
+	$(validate-tag)
+	cd version-upgrade-gen && go run . --workspace .. --tag $(TAG)
+	$(eval NEW_VERSION := $(shell cat .upgrade-version-tmp 2>/dev/null))
 	@rm -f .upgrade-version-tmp
+	$(MAKE) generate-talos-reference-local
 	$(MAKE) changelog
 	$(MAKE) docs.json
 	$(MAKE) validate-docs-nav
 	@echo ""
-	@echo "Upgrade to $(NEW_VERSION) complete! Run: make preview to preview your $(NEW_VERSION) docs"
+	@echo "Upgrade to $(TAG) complete! Run: make preview to preview your $(NEW_VERSION) docs"
 
 .PHONY: build-version-upgrade-container
 build-version-upgrade-container: ## Build the version-upgrade-gen container locally

contributing-guides/generating-docs.md

@@ -48,6 +48,19 @@ Both variants run `talosctl` from a container, so **Docker is required either wa
 
 **Versioning:** the output directory is chosen by `TALOS_VERSION` in the Makefile (e.g. `v1.14`), and the talosctl image is pinned by `TALOSCTL_IMAGE`. Older versions already committed under `public/talos/` are not touched.
 
+### Updating Talos docs for a new release
+
+When Talos cuts a new release — an alpha, beta, or stable — the docs need to point at it: the version pins, the versioned variables, the navigation, the reference pages, and the changelog. `make upgrade-talos-version` does all of that from a single tag instead of editing each by hand.
+
+```bash
+make upgrade-talos-version TAG=v1.14.0-alpha.0   # alpha
+make upgrade-talos-version TAG=v1.14.0-beta.0    # beta
+make upgrade-talos-version TAG=v1.14.0           # stable
+make upgrade-talos-version-local TAG=v1.14.0     # same, using the local Go build
+```
+
+See [`version-upgrade-gen/README.md`](../version-upgrade-gen/README.md) for the full details.
+
 ## Omni reference
 
 `make generate-omni-reference` regenerates all three Omni reference pages; each page also has its own target if you only need one:

public/snippets/custom-variables.mdx

@@ -72,9 +72,8 @@ export const nvidia_container_toolkit_release_v1_13 = "v1.19.0"
 export const nvidia_driver_release_v1_13 = "580.126.20"
 
 {/* 1.14 talos release */}
-export const release_v1_14 = 'v1.14.0-alpha.0'
+export const release_v1_14 = 'v1.14.0-alpha.2'
 export const release_branch_v1_14 = 'release-1.14'
 export const version_v1_14 = 'v1.14'
 export const nvidia_container_toolkit_release_v1_14 = "v1.19.0"
 export const nvidia_driver_release_v1_14 = "580.126.20"
-

version-upgrade-gen/README.md

@@ -1,51 +1,89 @@
 # version-upgrade-gen
 
-A Go tool that automates upgrading the Talos documentation to the next version.
+A Go tool that points the Talos documentation at a specific Talos release tag.
 
 ## What it does
 
-When run, it prompts you to select a release type and then:
-
-**Beta release**
-- Updates the versioned variables block in `custom-variables.mdx` with the new beta tag (e.g. `v1.14.0-beta.0`)
-- Adds the new `talos-vX.Y.yaml` at the bottom of the nav in all four Makefile targets so the beta version appears last in the version dropdown
-
-**Stable release**
-- Updates the "latest stable" block in `custom-variables.mdx` with the new version's Kubernetes and nvidia versions (fetched from GitHub)
-- Updates or creates the versioned variables block in `custom-variables.mdx`
-- Updates the version warning banner to point to the new latest version
-- Updates all canonical URLs across older version docs to point to the new version
-- Moves the new `talos-vX.Y.yaml` to the top of the nav in all four Makefile targets
-- Updates `TALOSCTL_IMAGE` and `TALOS_VERSION` in the Makefile
+You pass the exact target image tag with `--tag` (e.g. `v1.14.0-beta.0` or
+`v1.14.0`). The tool reads the current tag from `TALOSCTL_IMAGE` in the Makefile
+and derives everything else from the two tags:
+
+- **Stage** (alpha / beta / stable) comes from the tag's suffix — there is no
+  interactive prompt.
+- **Folder** (`TALOS_VERSION`, e.g. `v1.14`) is the tag's `major.minor`. Moving a
+  minor through alpha → beta → stable keeps the same folder; only a genuinely new
+  minor changes it.
+
+**Pre-release target (alpha/beta)**
+- Rewrites `TALOSCTL_IMAGE` to the exact tag and `TALOS_VERSION` to the folder minor
+- Updates (or appends) the versioned variables block in `custom-variables.mdx` with the tag
+- Leaves the "latest stable" pointer (banner, canonical URLs, latest-stable block) untouched
+- **Navigation differs by stage:**
+  - **alpha** — leaves the `docs.json`/`check-missing` nav lists unchanged. The reference
+    docs are still generated on disk, but the version stays out of the published nav.
+  - **beta** — ensures `talos-vX.Y.yaml` is present at the bottom of the nav in all four
+    Makefile targets so the version appears last in the dropdown. This is idempotent, so
+    a beta correctly adds the entry that an earlier alpha of the same minor skipped.
+
+**Stable target**
+- Rewrites `TALOSCTL_IMAGE` to the exact tag and `TALOS_VERSION` to the folder minor
+- Updates the "latest stable" block in `custom-variables.mdx` with the release's
+  Kubernetes (from the `siderolabs/talos` release notes) and nvidia versions, and
+  updates/creates the versioned block
+- Only when the latest stable minor actually changes (read from the version warning
+  banner, not from `TALOS_VERSION`): updates the banner, rewrites canonical URLs
+  across older version docs, and moves `talos-vX.Y.yaml` to the top of the nav
+
+**nvidia values (both paths)**
+The `nvidia_container_toolkit_release` / `nvidia_driver_release` values are resolved
+the same way everywhere: first from the `siderolabs/extensions` release notes for the
+exact tag, and — if that release is missing, has no nvidia fields, or the fetch fails —
+falling back to the current unversioned latest-stable values. They are therefore never
+written empty, and a stable run no longer aborts when the extensions data lags behind.
+For an existing versioned block, a pre-release only backfills nvidia values that are
+currently empty, so good values from an earlier stable run are never overwritten.
+
+The current image tag is matched in full, including any pre-release suffix, so a pin
+like `v1.14.0-alpha.2` is replaced cleanly rather than by prefix.
 
 ## Usage
 
-From the repo root:
+From the repo root, pass the target tag with `TAG=`:
 
 ```bash
-# Using local Go build
-make upgrade-talos-version-local
+# Published Docker container
+make upgrade-talos-version TAG=v1.14.0-beta.0     # beta of the current minor
+make upgrade-talos-version TAG=v1.14.0            # stable
+make upgrade-talos-version TAG=v1.15.0-beta.0     # first beta of a new minor
 
-# Using published Docker container
-make upgrade-talos-version
+# Local Go build
+make upgrade-talos-version-local TAG=v1.14.0-beta.0
 ```
 
-Both commands will prompt you interactively:
+After the tool rewrites the pins, the Makefile targets automatically regenerate the
+Talos reference docs (`make generate-talos-reference`), the changelog, and
+`docs.json`, then tell you to run `make preview` to verify the result.
 
-```
-What type of release is this?
-  [1] Beta   - e.g v1.14.0-beta.0
-  [2] Stable - e.g v1.14.0
+Running the binary directly:
 
-Enter your choice (1 or 2):
+```bash
+go run . --workspace .. --tag v1.14.0-beta.0
 ```
 
-After the tool runs, it automatically regenerates the changelog and `docs.json`, then tells you to run `make preview` to verify the result.
+## Tag validation
+
+The `--tag` value must be `vMAJOR.MINOR.PATCH` with an optional `-alpha.N` /
+`-beta.N` / `-rc.N` suffix (e.g. `v1.14.0`, `v1.14.0-beta.0`). Surrounding
+whitespace is trimmed. Anything else — a missing `v`, a missing patch number, a
+misspelled stage, etc. — is rejected up front, before any file is modified, so a
+typo can never leave the repo in a half-applied state.
 
 ## Prerequisites
 
-- A `talos-vX.Y.yaml` navigation file must already exist before running in either mode
-- For stable releases, a `GITHUB_TOKEN` environment variable is recommended to avoid GitHub API rate limits
+- A `talos-vX.Y.yaml` navigation file must already exist before running
+- A `GITHUB_TOKEN` is used for the stable release GitHub lookups (and by the
+  changelog step). The Makefile auto-fills it from `gh auth token` when it isn't
+  already set in the environment, so no manual export is normally needed.
 
 ## Building the container