From d14a4d2da1384390258f3b6a31138ba32fada7ae Mon Sep 17 00:00:00 2001 From: Ravi Tharuma <25951435+RaviTharuma@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:51:39 +0200 Subject: [PATCH] docs(docker): clarify latest tracks published stable SemVer (#10816) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merged — locally validated (changelog gate green) after resolving base-drift against #10817's SQLite HA section (both landed today, same insertion point in DOCKER_GUIDE.md — combined, both sections kept). Thanks! --- README.md | 2 ++ .../10317-latest-tracks-highest-stable.md | 1 + docs/getting-started/QUICK-START.md | 2 ++ docs/guides/DOCKER_GUIDE.md | 15 ++++++++++++--- docs/ops/RELEASE_CHECKLIST.md | 9 +++++++++ 5 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 changelog.d/maintenance/10317-latest-tracks-highest-stable.md diff --git a/README.md b/README.md index 43341e9895..fc66a61a71 100644 --- a/README.md +++ b/README.md @@ -988,6 +988,8 @@ docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` +`:latest` follows the highest **published** stable SemVer. It does not track git `main`. Pin `:X.Y.Z` for GitOps. See [Docker Release Channels](docs/guides/DOCKER_GUIDE.md#release-channels). + > **Pre-release Docker channel:** `diegosouzapw/omniroute:next` and > `diegosouzapw/omniroute:next-web` follow the current default `release/v*` > branch. These mutable tags are intended only for testing unreleased fixes and diff --git a/changelog.d/maintenance/10317-latest-tracks-highest-stable.md b/changelog.d/maintenance/10317-latest-tracks-highest-stable.md new file mode 100644 index 0000000000..9fdb4d2c81 --- /dev/null +++ b/changelog.d/maintenance/10317-latest-tracks-highest-stable.md @@ -0,0 +1 @@ +- **docs(docker):** spell out that `:latest` tracks the highest **published** stable SemVer (not git `main`), and that GitOps should pin `X.Y.Z` ([#10317](https://github.com/diegosouzapw/OmniRoute/issues/10317)) diff --git a/docs/getting-started/QUICK-START.md b/docs/getting-started/QUICK-START.md index d336934436..bed9fcb71e 100644 --- a/docs/getting-started/QUICK-START.md +++ b/docs/getting-started/QUICK-START.md @@ -26,6 +26,8 @@ npm install -g omniroute docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest ``` +`:latest` is the highest **published** stable SemVer. It does **not** track git `main`. Pin `diegosouzapw/omniroute:X.Y.Z` for GitOps. See [Image Tags / Release Channels](../guides/DOCKER_GUIDE.md#release-channels). + ### Option C: From Source ```bash diff --git a/docs/guides/DOCKER_GUIDE.md b/docs/guides/DOCKER_GUIDE.md index e1b639bcf8..40487ee6cc 100644 --- a/docs/guides/DOCKER_GUIDE.md +++ b/docs/guides/DOCKER_GUIDE.md @@ -412,8 +412,8 @@ Endpoint tunnel panels (Cloudflare, Tailscale, ngrok) can be shown or hidden fro | Image | Tag | Size | Description | | ------------------------ | -------- | ------ | --------------------- | -| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release | -| `diegosouzapw/omniroute` | `3.8.0` | ~250MB | Current version | +| `diegosouzapw/omniroute` | `latest` | ~250MB | Highest **published** stable SemVer (not git `main`) | +| `diegosouzapw/omniroute` | `3.8.0` | ~250MB | Pin this class of tag for GitOps | Multi-platform manifest: `linux/amd64` + `linux/arm64` native (Apple Silicon, AWS Graviton, Raspberry Pi). Docker selects the matching architecture automatically; pass `--platform linux/amd64` if you need to force AMD64 emulation on ARM hosts. @@ -424,7 +424,7 @@ OmniRoute publishes separate Docker channels for stable releases, active release | Channel | Source | Mutability | Recommended use | | ------------------------------- | ----------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------- | | `:` / `:-web` | Signed/versioned release | Immutable | Production deployments that pin an exact release | -| `:latest` / `:latest-web` | Highest stable release | Mutable stable pointer | Production deployments that intentionally follow stable releases | +| `:latest` / `:latest-web` | Highest **published** stable SemVer | Mutable stable pointer | Follows stable releases **after** a SemVer publish job — does **not** track `main` or unreleased `release/v*` commits | | `:next` / `:next-web` | Current default `release/v*` branch | Mutable pre-release pointer | Testing fixes that have landed on the active release branch but are not yet in a stable release | | `:main` / `:main-web` | `main` branch | Mutable development pointer | Development and integration testing only | @@ -468,6 +468,15 @@ docker compose up -d A release-branch build can never move `latest`; only an eligible stable semantic version may promote the stable pointer. The `next` images retain the release image inspection and blocking CRITICAL-vulnerability gate. +**`latest` is not a currency guarantee for git.** Merged fixes on `main` or on the active `release/v*` branch are **not** in `:latest` until a stable SemVer image is published and the publish job promotes `:latest` (same digest as that SemVer). If `latest` looks frozen while GitHub already shows the fix, pull `:next` to test the release branch or wait for the SemVer tag. + +| You want | Use | +| --- | --- | +| GitOps / production that must not drift | Pin `:X.Y.Z` (or the image digest) | +| Follow published stables and accept a recreate on each release | `:latest` | +| Test unreleased `release/v*` commits | `:next` (not production) | +| Test `main` | `:main` (not production) | + ## Availability: default SQLite is single-replica Stock Docker / Kubernetes OmniRoute is **one Node process + one SQLite writer**. High availability is **not supported** on that topology. diff --git a/docs/ops/RELEASE_CHECKLIST.md b/docs/ops/RELEASE_CHECKLIST.md index b800d6fc22..310bd5cf84 100644 --- a/docs/ops/RELEASE_CHECKLIST.md +++ b/docs/ops/RELEASE_CHECKLIST.md @@ -66,6 +66,15 @@ as the default reflex (minutes, reversible); `npm unpublish` only inside the 72h window and never as the first move. Docker: never rewrite a version tag — rollback is repointing `latest` to the last good digest. +**Docker Hub `latest` (required on every stable SemVer publish):** the +`docker-publish` workflow must tag **both** `X.Y.Z` and, when +`should-promote-latest.sh` agrees this is the highest stable SemVer, `:latest` +with the **same digest**. After the job: Hub `latest` digest equals the new +SemVer digest and `last_updated` moved. Do not leave `:latest` on an older +build while release notes talk about fixes that only exist on git. Compose +quickstarts use `:latest`; GitOps should keep pinning `X.Y.Z`. See +[Docker release channels](../guides/DOCKER_GUIDE.md#release-channels) and #10317. + ## Hotfix Fast-Lane (label `hotfix`) A PR labeled `hotfix` skips the heavy CI matrix (9-shard E2E, coverage ratchet,