From b9e42591f53d3e5dbee136f4ee53020461c3e2ba Mon Sep 17 00:00:00 2001
From: Paul Nothaft <53005142+the-luap@users.noreply.github.com>
Date: Tue, 4 Aug 2026 17:30:18 +0200
Subject: [PATCH] docs: the retired registry path freezes, it does not stop
 serving (#995)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #985.

README and migration-to-org.md both claimed the old path 'is no longer served'.
It is served — ghcr.io/the-luap/picpeak/backend:latest returns a complete image,
created 2026-05-27, label version: main. The registry responds normally; it just
never receives anything new.

That inaccuracy is what generates reports like #982. Told the path is not
served, an operator runs docker compose pull, watches it succeed, runs docker
rmi and pulls again, watches that succeed too, and concludes the problem lies
somewhere other than their image path. Nothing reports an error anywhere; the
only symptom is an update notice that never resolves.

Say what actually happens — the path freezes rather than failing — and add a
self-diagnosis via docker image inspect on both paths, with the 2026-05-27 date
and the 'main' version label as the tells. MigrationBanner's wording is left
alone: 'no longer being updated' was accurate.

This is the delivery mechanism for #985. There is no in-app channel:
MigrationBanner shipped a month after the freeze, the #993 update-check notice
cannot fire on installs running their own frozen backend, and the changelog
modal that renders release notes shipped two days after the freeze. What reaches
these operators is GitHub, and the GHCR page for the retired package — which
renders this README through the images' own org.opencontainers.image.source
label, so the fix propagates to the dead path's own page automatically.
---
 README.md                |  3 ++-
 docs/migration-to-org.md | 33 +++++++++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5abea197..91a29557 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,8 @@
 > [!IMPORTANT]
 > **PicPeak has moved to its own GitHub organization.**
 >
-> - **Docker images** are now published at `ghcr.io/picpeak/picpeak/{backend,frontend}`. The old path (`ghcr.io/the-luap/picpeak/...`) is no longer served — update your `docker-compose.yml`.
+> - **Docker images** are now published at `ghcr.io/picpeak/picpeak/{backend,frontend}`. Update your `docker-compose.yml`.
+> - ⚠️ The old path (`ghcr.io/the-luap/picpeak/...`) **still responds, but its tags are frozen** at 2026-05-27. `docker compose pull` succeeds and hands back the same build every time, so an out-of-date install looks like a broken download rather than a dead path. If PicPeak keeps reporting an update that never arrives, check your image path first.
 > - **Branches**: active development is now on `main` (was `beta`); the curated stable channel is now `stable` (was `main`). Existing PRs and clones auto-redirect via GitHub.
 >
 > See **[`docs/migration-to-org.md`](docs/migration-to-org.md)** for the one-line `docker-compose.yml` edit and full details.
diff --git a/docs/migration-to-org.md b/docs/migration-to-org.md
index 3ff2ba45..d6abf401 100644
--- a/docs/migration-to-org.md
+++ b/docs/migration-to-org.md
@@ -14,8 +14,37 @@ itself is unchanged; only the URLs you pull images from have moved.
 | **Branches (stable channel)** | `main` | `stable` |
 
 **Action required**: update your `docker-compose.yml` to pull from
-`ghcr.io/picpeak/picpeak/{backend,frontend}`. The old path no longer serves
-images.
+`ghcr.io/picpeak/picpeak/{backend,frontend}`.
+
+## The old path does not fail — it freezes
+
+This is the part that catches people out. `ghcr.io/the-luap/picpeak/*` **still
+serves**; it simply stopped receiving new images on 2026-05-27. So:
+
+- `docker compose pull` succeeds.
+- `docker rmi <image>` followed by a fresh pull succeeds.
+- You get byte-identical layers every time, because the tag never moves again.
+
+Nothing anywhere reports an error. The only visible symptom is that PicPeak keeps
+telling you an update is available and the update never arrives — which reads
+like a broken download rather than a retired registry path.
+
+### Am I affected?
+
+```bash
+docker image inspect ghcr.io/the-luap/picpeak/backend:latest \
+  --format '{{.Created}} {{index .Config.Labels "org.opencontainers.image.version"}}'
+```
+
+A `Created` date of `2026-05-27` (or a `version` of `main` rather than a `v3.x.y`
+tag) means you are on the retired path. Compare against the current image:
+
+```bash
+docker image inspect ghcr.io/picpeak/picpeak/backend:latest --format '{{.Created}}'
+```
+
+If your compose file still references `the-luap`, the fix below is all you need —
+there is nothing wrong with your install.
 
 ## Why this changed