docs: update the upgrade talos version make target

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

Author: Iheanacho-ai

Makefile

@@ -16,6 +16,11 @@ 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.
+GITHUB_TOKEN ?= $(shell gh auth token 2>/dev/null)
+
 # Default target
 .PHONY: help
 help: ## Show this help message
@@ -332,28 +337,32 @@ validate-docs-nav: ## Validate all talos yaml nav configs match their content di
 	cd docs-validate && go run . --workspace ..
 
 .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; }
 	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; }
+	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

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,81 @@
 # 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.
-
 ## 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