From f027ee5492640aa605f65cc710a9e71363e59d27 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 20 Aug 2026 09:02:25 +0200 Subject: [PATCH] =?UTF-8?q?Add=20KAIZEN-WP-0010=20=E2=80=94=20migrate=20pa?= =?UTF-8?q?ckage=20distribution=20to=20forgejo=20before=202026-08-31?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drafted by prj-state-hub-retirement from the estate-wide gitea sweep. kaizen-agentic appears to be the only repo that never migrated off the gitea PyPI index, which dies with CoulombCore on 2026-08-31. The Makefile publishes there and six documents instruct users to install from it. The workplan's one structural rule is publish-before-repoint: changing the docs first points users at a 404 instead of a soon-to-be-404, and today's instructions at least work. Proposed and unapplied — the packaging decisions belong to this repo. Co-Authored-By: Claude Opus 5 --- ...-agentic-WP-0010-forgejo-pypi-migration.md | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 workplans/kaizen-agentic-WP-0010-forgejo-pypi-migration.md diff --git a/workplans/kaizen-agentic-WP-0010-forgejo-pypi-migration.md b/workplans/kaizen-agentic-WP-0010-forgejo-pypi-migration.md new file mode 100644 index 0000000..8445c85 --- /dev/null +++ b/workplans/kaizen-agentic-WP-0010-forgejo-pypi-migration.md @@ -0,0 +1,164 @@ +--- +id: KAIZEN-WP-0010 +type: workplan +title: "Migrate package distribution from gitea to forgejo before CoulombCore retires" +domain: agents +repo: kaizen-agentic +status: proposed +owner: kaizen-agentic +topic_slug: custodian +created: "2026-08-20" +updated: "2026-08-20" +depends_on: [] +tasks: + - id: T01 + status: todo + title: Establish whether kaizen-agentic packages already exist on forgejo + - id: T02 + status: todo + title: Publish current versions to the forgejo PyPI index + - id: T03 + status: todo + title: Repoint Makefile and all six docs in one change + - id: T04 + status: todo + title: Verify a clean install from forgejo on an uncached machine + - id: T05 + status: todo + title: Retire the gitea variables and close out +--- + +# KAIZEN-WP-0010 — Migrate package distribution to forgejo + +**Deadline: 2026-08-31.** Not a target — CoulombCore is being decommissioned by +the operator on that date. + +## Why this exists + +`gitea.coulomb.social` runs on CoulombCore and serves two things: a container +registry and a **PyPI package index** at `/api/packages/coulomb/pypi`. Both stop +existing when the host does. + +kaizen-agentic appears to be the only repo in the estate that never migrated. +The rest moved in early July — `issue-core` carries both endpoints +(`Makefile:68` gitea, `Makefile:69` forgejo, publish targets at `240` and `250`), +and `vergabe-teilnahme/pyproject.toml` already points at +`forgejo.coulomb.social/api/packages/coulomb/pypi/simple/`. So the destination +exists and is in use; this repo was missed. + +### What breaks, and why it is worse than a broken link + +``` +Makefile:10 GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi +Makefile:11 GITEA_PYPI_SIMPLE_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/ +``` + +and the install instructions in **six** documents — `README.md`, +`docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`, +`docs/PACKAGE_RELEASE.md`, `docs/HELLO_WORLD_TUTORIAL.md`, +`docs/CLI_CHEAT_SHEET.md` — all tell users to +`pip install --extra-index-url …@gitea.coulomb.social/api/packages/coulomb/pypi/simple/`. + +These are the documented install instructions for the kaizen agent +distribution. After 2026-08-31 every one fails, and it fails *looking like a +broken package* rather than a retired host — so the person hitting it will debug +the wrong thing. + +## The one rule for sequencing + +**Publish before you repoint.** A registry migration is not a find-and-replace. +If the docs change first, they point at a 404 instead of a soon-to-be-404, which +is strictly worse: today's instructions at least work. T01 and T02 come before +T03, and T03 is a single change covering the Makefile and all six documents +together — a half-migrated doc set is how the next repo gets missed. + +## Tasks + +```task +id: KAIZEN-WP-0010-T01 +status: todo +priority: high +``` + +**Establish whether kaizen-agentic packages already exist on forgejo.** Check +`forgejo.coulomb.social/api/packages/coulomb/pypi` for current package names and +versions. This is a read; do not publish yet. + +Record what is there against what gitea holds. If forgejo already has current +versions, T02 becomes a no-op and this finishes much faster than feared — worth +five minutes before assuming a full republication. + +Credentials: this needs a forgejo package token, not a gitea one. Route through +`warden plan "forgejo package publish token"` rather than reusing +`GITEA_PACKAGE_TOKEN`, and never paste a token into the Makefile or a doc. + +```task +id: KAIZEN-WP-0010-T02 +status: todo +priority: high +``` + +**Publish current versions to the forgejo PyPI index.** Only the versions that +matter — whatever the docs tell users to install, plus the current release. +Historical versions are a judgement call: republish them only if something +actually pins an old version. + +`issue-core/Makefile:250` is a working example of the forgejo `twine upload` +target and is the shortest path to a correct invocation. + +```task +id: KAIZEN-WP-0010-T03 +status: todo +priority: high +``` + +**Repoint the Makefile and all six docs in one change.** Add +`FORGEJO_PYPI_REPOSITORY_URL` / `FORGEJO_PYPI_SIMPLE_URL` and make them the +default path, then update every install instruction listed above. + +Decide deliberately whether to keep the gitea variables temporarily for +comparison or delete them now. `issue-core` kept both and now carries a legacy +target that fails after 08-31 — a trap for whoever runs the wrong `make`. Given +the deadline is nine days after this workplan is written, deleting outright is +probably the better call here, but make it a decision rather than a default. + +Also update `GITEA_PACKAGE_USER` / `GITEA_PACKAGE_TOKEN` variable *names* if you +keep the credential envelope — a variable called `GITEA_*` pointing at forgejo is +the kind of thing that survives for years and confuses everyone who reads it. + +```task +id: KAIZEN-WP-0010-T04 +status: todo +priority: high +``` + +**Verify a clean install from forgejo on a machine with no cache.** A `pip +install` that succeeds because the wheel is already in a local cache proves +nothing. Use a fresh venv and `--no-cache-dir`, following the README's own +instructions verbatim — if the documented command does not work, the docs are +still wrong regardless of what the registry holds. + +This is the task that actually closes the risk. T01–T03 are preparation. + +```task +id: KAIZEN-WP-0010-T05 +status: todo +priority: medium +``` + +**Close out.** Remove any remaining gitea references from operational files +(`Makefile`, docs, CI). Leave alone anything that merely *records* that gitea +existed — history stays true after the host is switched off, and rewriting it to +tidy a grep loses information. + +Tell `prj-state-hub-retirement` when T04 passes; this is tracked there as +`SHR-WP-0002-T07` and is one of two items gating CoulombCore's retirement. + +## Notes + +- Drafted by `prj-state-hub-retirement` on 2026-08-20 from the estate-wide sweep + that found this repo. The sequencing rule and the deadline are ours; **the + packaging decisions are yours** — nothing here has been applied to your files. +- If any of this is wrong about how kaizen-agentic actually publishes, trust + your own knowledge and tell the project. The sweep read your Makefile and + docs; it did not run your release process.