pi
c8217814c8
Validate / docs-check (push) Failing after 7s
Validate / base-change-warning (push) Successful in 9s
Validate / validate-omos (push) Successful in 4m21s
Validate / validate-with-pi (push) Successful in 7m27s
Validate / validate-omos-with-pi (push) Successful in 5m52s
Validate / validate-base (push) Successful in 11m15s
Validate / validate-pi-only (push) Successful in 6m32s
Document that base-pi-only / base-pi-only-vX.Y.Z on joakimp/pi-devbox are orphaned legacy artifacts (no pi-devbox build input references them) that the build-variant-pi-only job re-publishes every release. Purge them from the pi-devbox Hub repo after PR-5 removes the publisher; before that, the floating tag just reappears. Added to removal steps + verification.
248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# PR-5: Retire pi from opencode-devbox
|
||
|
||
After pi-devbox has shipped v1.0.0 as a fully independent image (with
|
||
its own base + variant Dockerfiles, CI, smoke tests, and docs), the
|
||
pi-related paths in opencode-devbox become dead weight. This PR
|
||
removes them.
|
||
|
||
## Pre-conditions before merging
|
||
|
||
This PR should land **only after** all of the following are stable:
|
||
|
||
1. `pi-devbox v1.0.0` published, smoke tests passing, in active use
|
||
for at least one release cycle.
|
||
2. Anyone consuming `joakimp/pi-devbox:base-pi-only` directly (e.g.
|
||
forks pinned to it) has been notified and migrated.
|
||
3. The deprecation warning (PR-1 of this work — see below) has been
|
||
live for at least one release cycle so consumers have visible
|
||
notice.
|
||
|
||
## Files / sections to remove from opencode-devbox
|
||
|
||
### `Dockerfile.variant`
|
||
|
||
Remove these blocks entirely:
|
||
|
||
- The `INSTALL_PI` / `PI_VERSION` / `PI_TOOLKIT_REF` /
|
||
`PI_EXTENSIONS_REF` / `PI_FORK_REPO` / `PI_FORK_REF` /
|
||
`PI_OBSMEM_REPO` / `PI_OBSMEM_REF` build-args.
|
||
- The `RUN if [ "${INSTALL_PI}" = "true" ]; then ...` block (entire
|
||
block — git_clone_retry, git_fetch_ref, npm install
|
||
pi-coding-agent, the four /opt/pi-* clones, the npm installs in
|
||
/opt/pi-fork and /opt/pi-observational-memory, and the four
|
||
rev-parse echoes).
|
||
- All comments referencing pi-only as "the single source of truth for
|
||
the pi-devbox image" (the variant matrix table, the explanatory
|
||
paragraph, and the "rationale" comments at the top of the file
|
||
about pi-only existing for pi-devbox to FROM).
|
||
|
||
Update the variant matrix table at the top of `Dockerfile.variant`:
|
||
|
||
```
|
||
variant INSTALL_OPENCODE INSTALL_OMOS
|
||
───────────────── ──────────────── ────────────
|
||
base true false
|
||
omos true true
|
||
```
|
||
|
||
(only two variants now; pi-only and the with-pi/omos-with-pi axis are
|
||
gone).
|
||
|
||
### `entrypoint-user.sh`
|
||
|
||
Remove:
|
||
|
||
- The pi-toolkit and pi-extensions install hooks (the section that
|
||
runs `(cd /opt/pi-toolkit && ./install.sh --yes)` etc.).
|
||
- The `~/.pi/agent/settings.json` seeding from
|
||
`/opt/pi-toolkit/settings.example.json`.
|
||
- Any other pi-conditional blocks (search for `INSTALL_PI`, `pi-toolkit`,
|
||
`pi-extensions`, `~/.pi/`).
|
||
|
||
Verify that the AWS Bedrock auth bootstrap (the pi-toolkit AWS env
|
||
loader) is not relied on by opencode users. If it is, lift it out of
|
||
the pi-toolkit dependency (it's small and self-contained).
|
||
|
||
### `Dockerfile.base`
|
||
|
||
Remove:
|
||
|
||
- The `mkdir -p /home/${USER_NAME}/.pi/agent/extensions` line in the
|
||
standard-directories block. Replace with the equivalent opencode-
|
||
specific paths if any aren't already present (`~/.config/opencode`
|
||
is already there).
|
||
- `NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global` — change to
|
||
`/home/${USER_NAME}/.config/opencode/npm-global` or a more neutral
|
||
path. Update the corresponding `PATH` env var.
|
||
|
||
Also update the long base-image header comment to remove the
|
||
"variants for pi-devbox" rationale.
|
||
|
||
### CI (`.gitea/workflows/docker-publish-split.yml` or equivalent)
|
||
|
||
Remove:
|
||
|
||
- The `pi-only` variant build job.
|
||
- The `with-pi` and `omos-with-pi` variant build jobs (they're
|
||
redundant with the standalone pi-devbox now).
|
||
- The `base-pi-only` tag publish step (which pushes to
|
||
`joakimp/pi-devbox:base-pi-only` from this repo).
|
||
- The `resolve-pi-version` job step (no longer needed).
|
||
- Smoke-test invocations with `--variant pi-only`, `--variant with-pi`,
|
||
`--variant omos-with-pi`.
|
||
|
||
Remaining variants in CI: `base`, `omos`. The "with-pi" axis is
|
||
fully retired.
|
||
|
||
### `scripts/smoke-test.sh`
|
||
|
||
Remove:
|
||
|
||
- The `--variant pi-only`, `--variant with-pi`, `--variant
|
||
omos-with-pi` branches.
|
||
- pi-related assertions: `pi --version`, the
|
||
`~/.pi/agent/extensions/*.ts ≥ 4` check, the mempalace.ts bridge
|
||
gate (mempalace itself stays, but its bridge into pi is no longer
|
||
this image's concern).
|
||
|
||
Remaining variant axis in smoke tests: `base`, `omos`.
|
||
|
||
### `README.md` (and `AGENTS.md`, `DOCKER_HUB.md`)
|
||
|
||
- Remove the pi-only variant from the "Image variants" table.
|
||
- Remove the with-pi / omos-with-pi variants if they were documented.
|
||
- Remove all sections about pi-toolkit, pi-extensions, pi-fork,
|
||
pi-observational-memory, ~/.pi paths, and pi-related env vars.
|
||
- Remove the "this image also produces base-pi-only for pi-devbox"
|
||
notes.
|
||
- Add a single-paragraph **"Looking for pi?"** section pointing to
|
||
`joakimp/pi-devbox`.
|
||
|
||
### `Dockerfile` references in `pi-devbox` repo (cleanup of cross-repo coupling)
|
||
|
||
This isn't a change to opencode-devbox, but it's part of the same
|
||
deprecation:
|
||
|
||
- Once pi-devbox v1.0.0 is the single source of truth, remove
|
||
pi-devbox/Dockerfile (the 5-line shim with the long
|
||
`joakimp/pi-devbox:base-pi-only` rationale comment). It's replaced
|
||
by `Dockerfile.base` + `Dockerfile.variant` produced by PR-1 of
|
||
this work.
|
||
|
||
### Purge the orphaned `base-pi-only*` Hub tags (manual, post-merge)
|
||
|
||
Until PR-5, the `build-variant-pi-only` job re-publishes
|
||
`joakimp/pi-devbox:base-pi-only` (floating) and a fresh
|
||
`base-pi-only-vX.Y.Z` on **every** opencode-devbox release. These tags
|
||
are orphaned legacy artifacts: pi-devbox v1.0.0+ builds its own
|
||
debian-based `base-<hash>` and **no pi-devbox build input references
|
||
`base-pi-only`** (verified 2026-06-10 — only historical mentions remain
|
||
in pi-devbox's CHANGELOG/AGENTS/DOCKER_HUB). Nothing consumes them.
|
||
|
||
Once PR-5 deletes the `build-variant-pi-only` job, the publisher is
|
||
gone — so this is the moment to purge the accumulated tags from the
|
||
**`joakimp/pi-devbox`** Docker Hub repo (NOT opencode-devbox):
|
||
|
||
- Delete the floating `base-pi-only` tag.
|
||
- Delete every versioned snapshot: `base-pi-only-v1.17.2`,
|
||
`base-pi-only-v1.16.2`, `base-pi-only-v1.15.13e`, … (all of them).
|
||
|
||
Do this **after** PR-5 is merged and the first post-PR-5 release has
|
||
built, to confirm no new `base-pi-only*` tag reappears. If you purge
|
||
before PR-5, the next opencode-devbox release simply recreates the
|
||
floating tag (whack-a-mole). Deletion is via the Hub UI
|
||
(`hub.docker.com/r/joakimp/pi-devbox/tags`) or the Hub API
|
||
(`DELETE /v2/repositories/joakimp/pi-devbox/tags/<tag>/` with a Hub PAT).
|
||
|
||
## Two-step deprecation path (recommended)
|
||
|
||
Rather than a single big-bang removal, use a deprecation cycle:
|
||
|
||
### Step 1 — pre-PR (lands at the same time as pi-devbox v1.0.0)
|
||
|
||
Add a deprecation warning to opencode-devbox:
|
||
|
||
1. **Build-time message** — when `INSTALL_PI=true`,
|
||
`INSTALL_PI_DEPRECATED=warn` is the default; the variant build
|
||
prints to stderr:
|
||
```
|
||
===========================================================
|
||
DEPRECATION WARNING: INSTALL_PI is deprecated in opencode-devbox
|
||
and will be removed in v2.0.0. Use joakimp/pi-devbox:latest
|
||
instead. See https://gitea.jordbo.se/joakimp/pi-devbox
|
||
===========================================================
|
||
```
|
||
2. **CHANGELOG** entry on opencode-devbox: "INSTALL_PI build-arg path
|
||
deprecated; will be removed in v2.0.0."
|
||
3. **README and DOCKER_HUB** updates: mark `pi-only`, `with-pi`,
|
||
`omos-with-pi` variants as deprecated, point to pi-devbox.
|
||
4. The `base-pi-only` tag continues to be published but with a
|
||
notice in the description: "Internal artifact for pi-devbox.
|
||
Deprecated; pull joakimp/pi-devbox:latest directly."
|
||
|
||
### Step 2 — removal PR (this document)
|
||
|
||
Lands one release cycle (or one calendar month, whichever is later)
|
||
after step 1. Removes everything listed in the per-file sections
|
||
above. Tagged as opencode-devbox v2.0.0 (the major bump signals the
|
||
breaking change).
|
||
|
||
## Risk assessment
|
||
|
||
### What could go wrong
|
||
|
||
- **Someone is consuming `base-pi-only` directly** without going
|
||
through pi-devbox. The deprecation warning + one-cycle delay should
|
||
surface this.
|
||
- **Mempalace bridge in pi-extensions** — this stays in pi-devbox; no
|
||
impact on opencode-devbox.
|
||
- **Shared base assumptions** — opencode-devbox's
|
||
`~/.pi/npm-global` NPM_CONFIG_PREFIX was a pi-specific design. In
|
||
the cleanup we move it to a neutral path. Existing opencode-devbox
|
||
users get a one-time migration: their `npm install -g` packages
|
||
installed at the old path stop being on PATH. Document this in the
|
||
v2.0.0 changelog and add a one-liner that copies the old prefix
|
||
contents to the new one if the old one exists.
|
||
|
||
### What's safe
|
||
|
||
- The base apt set, the Go-binary installs, MemPalace, the SSH
|
||
ControlMaster setup, the entrypoint UID/GID dance — all of these
|
||
stay. They're not pi-specific.
|
||
- The `omos` variant — fully unaffected.
|
||
- Existing opencode-only users — no change to their workflow.
|
||
|
||
## Verification
|
||
|
||
After PR-5 lands, the following should be true:
|
||
|
||
- `grep -ri "INSTALL_PI\|pi-toolkit\|pi-extensions\|pi-fork\|pi-observational-memory\|base-pi-only" .` in opencode-devbox returns no matches.
|
||
- `docker history joakimp/opencode-devbox:latest` shows no pi-related layers.
|
||
- The opencode-devbox CI matrix builds only `base` and `omos` variants.
|
||
- A post-PR-5 release does NOT recreate any `joakimp/pi-devbox:base-pi-only*` tag (publisher confirmed gone), after which those orphaned tags are purged from the pi-devbox Hub repo.
|
||
- pi-devbox CI is unaffected (it's a different repo).
|
||
- Both repos build cleanly in their own CI without referencing the other.
|
||
|
||
## Estimated effort
|
||
|
||
- Step 1 (deprecation warnings): ~2 hours.
|
||
- Step 2 (removal): ~4 hours including local testing of opencode-only
|
||
build paths.
|
||
- One release cycle of monitoring between them.
|
||
|
||
Total: ~1 working day of focused effort, spread over a calendar month.
|
||
|
||
## Order in the broader plan
|
||
|
||
1. PR-1 on pi-devbox — copy base + variant Dockerfiles, strip
|
||
opencode/omos paths, tag v1.0.0.
|
||
2. PR-2 on pi-devbox — add pandoc, graphviz, imagemagick, tldr, yq.
|
||
3. PR-3 on pi-devbox — add `:latest-studio` variant.
|
||
4. (Optional) PR-4 on pi-devbox — add `:latest-studio-tex` variant.
|
||
5. PR-pre on opencode-devbox — deprecation warnings (step 1 above).
|
||
6. **PR-5 on opencode-devbox — actual removal (this document, step 2).**
|
||
|
||
PRs 1–4 are independent and can land in any order on pi-devbox. PR-pre
|
||
should land alongside or shortly after pi-devbox v1.0.0 (PR-1) so
|
||
consumers know to migrate. PR-5 lands one release cycle after PR-pre.
|