From d29dd10fbd4c9d776c608f2a193c6697a0dc761e Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Wed, 24 Jun 2026 22:28:43 -0400 Subject: [PATCH] docs: document one-time apt codename prompt for v3.2.2+ upgrades Users who had the v3 repo configured before v3.2.2 see an apt security prompt when the Codename field changed from unset to 'error'. Document the --allow-releaseinfo-change one-liner in README, getting-started.md (new section 6.8), and upgrade-paths.md (codename column + callout). Closes #284. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 8 ++++++++ docs/getting-started.md | 12 ++++++++++++ docs/upgrade-paths.md | 21 +++++++++++++++------ 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c9a750b..81e5210 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,14 @@ sudo apt update && sudo apt install truenas-proxmox automatically promoted to a future v4 — that requires changing the dist track in your `sources.list` to `v4`. +> **Existing users — one-time prompt after v3.2.2** +> If `apt update` shows `changed its 'Codename' value from 'v3' to 'error'`, run: +> ```bash +> apt update --allow-releaseinfo-change +> ``` +> This happened once when codename aliases were added in v3.2.2. It will not recur. +> Both `v3` (Suite) and `error` (Codename) continue to work in `sources.list`. + ### Upgrading from v2.x **v3.0 is a breaking change.** Do not run `apt upgrade` until you have read the diff --git a/docs/getting-started.md b/docs/getting-started.md index f9dc27e..cc5319c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -289,6 +289,18 @@ This is expected and not an error. Proxmox creates disks in GiB (base-2) but Tru TPM state (`tpmstate0`) is a known limitation — this storage type cannot hold TPM state disks. When creating a VM with TPM/Secure Boot, configure a different storage (such as `local-lvm` or NFS) for the `tpmstate0` disk. All other disk types work normally. +### 6.8 `apt update` Says Codename Changed from `v3` to `error` + +This is a one-time prompt from apt's security model. In v3.2.2, a codename alias (`error`) was added to the `v3` dist — apt flags metadata changes like this and requires explicit acceptance before continuing. + +Run this once: + +```bash +apt update --allow-releaseinfo-change +``` + +After that, `apt update` works normally and this prompt will not appear again for any future v3.x release. Both `v3` (Suite) and `error` (Codename) work in `sources.list` and point to the same packages. + --- ## 7. Uninstalling diff --git a/docs/upgrade-paths.md b/docs/upgrade-paths.md index aa0b196..16c581d 100644 --- a/docs/upgrade-paths.md +++ b/docs/upgrade-paths.md @@ -93,11 +93,20 @@ sudo apt update ## Dist track reference -| Dist track | Contains | Who should use it | -|---|---|---| -| `main` | v2.x packages only | Users staying on v2.x | -| `v2` | v2.x packages (alias for `main`) | Same as `main` — explicit pin | -| `v3` | v3.x packages only | All current v3 installs | -| `v4` | v4.x packages only | Added when v4.0 ships | +| Dist track | Codename alias | Contains | Who should use it | +|---|---|---|---| +| `main` | `limelight` | v2.x packages only | Users staying on v2.x | +| `v2` | `limelight` | v2.x packages (alias for `main`) | Same as `main` — explicit pin | +| `v3` | `error` | v3.x packages only | All current v3 installs | +| `v4` | `rivendell` | v4.x packages only | Added when v4.0 ships | + +Both the dist track (`v3`) and its codename alias (`error`) work in `sources.list` — they resolve to the same packages. Packages on one dist track are never promoted to another. Changing major versions always requires an explicit `sources.list` edit. + +> **Existing v3 users — one-time prompt after v3.2.2** +> If `apt update` reports `changed its 'Codename' value from 'v3' to 'error'`, run: +> ```bash +> apt update --allow-releaseinfo-change +> ``` +> This is a one-time acknowledgment of the codename being added in v3.2.2. It will not recur.