joakimp/opencode-devbox
Public Access
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AGENTS.md: expand doc-coupling rule with release-day checklist
Validate / docs-check (push) Successful in 14s
Details
Validate / validate-base (push) Successful in 11m9s
Details
Validate / validate-omos (push) Successful in 16m33s
Details
Validate / validate-with-pi (push) Successful in 12m9s
Details
Validate / validate-omos-with-pi (push) Successful in 16m41s
Details

Browse Source 
The previous 'Two docs to keep in sync' bullet only mentioned
README + DOCKER_HUB.md + .env.example. Today's session surfaced
two additional drift points the rule didn't cover:

- CHANGELOG.md still claimed 'Unreleased — will become v1.14.41b
  on release' even though the tag had been pushed and shipped
  (caught a full session later when user asked about doc drift).
- AGENTS.md itself carried stale 'four Docker Hub tags' /
  'four load:true jobs' from before the v1.14.41b CI matrix
  expansion to eight.

Replaced the bullet with a full 'Documentation coupling on release'
rule listing all four coupled docs (README, DOCKER_HUB.md,
CHANGELOG.md, AGENTS.md, plus .env.example) and an explicit
release-day checklist. Calls out the 25 kB Hub limit on
DOCKER_HUB.md as a hard constraint to keep in mind when adding
sections to README.
This commit is contained in:
Joakim Persson
2026-05-08 21:35:23 +02:00
parent cc98722d84
commit 148f4bce8c
1 changed files with 8 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+8 -1
View File
@@ -33,7 +33,14 @@ When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile`
## Critical conventions ## Critical conventions
- **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup. The loop writes a `.devbox-owner` sentinel after a successful chown so subsequent starts skip the recursive walk. Users should not touch these files. - **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup. The loop writes a `.devbox-owner` sentinel after a successful chown so subsequent starts skip the recursive walk. Users should not touch these files.
- **Two docs to keep in sync (automated)** — `README.md` is the source of truth. `DOCKER_HUB.md` is auto-generated by `scripts/generate-dockerhub-md.py`. When adding a new top-level section to README, either add it to `SECTION_RULES` in that script or the `--check` run will fail CI. `.env.example` must still be hand-updated to match Dockerfile/entrypoint behavior. - **Documentation coupling on release** — four docs co-vary and drift in lockstep when not updated together:
- `README.md` is the source of truth for user-facing build/run/config detail.
- `DOCKER_HUB.md` is auto-generated by `scripts/generate-dockerhub-md.py` from README. CI's `--check` run fails if it's stale or any new top-level README section is missing from `SECTION_RULES`. Hard cap: 25 kB Hub limit (current: ~24.9 kB, very tight — trim before adding).
- `CHANGELOG.md` records every release. When cutting a tag, **promote `## Unreleased` to `## vX.Y.Z[n] — YYYY-MM-DD` BEFORE pushing the tag** so the tag points at a CHANGELOG that names itself. Keep entries reverse-chronological (newest at top, after the `Unreleased` block). Doc-only updates that happen post-tag (Hub description live-patches, README clarifications) get a fresh `## Unreleased` block with a note that they don't trigger a new image build.
- `AGENTS.md` (this file) carries domain facts that change on structural releases — tag-count statements, CI job lists, install contracts. After any change to `.gitea/workflows/*.yml` or the variant matrix, grep this file for stale numbers (`grep -nE "four|eight|all [0-9]"`).
- `.env.example` must be hand-updated to match Dockerfile/entrypoint behavior — it is not auto-generated.
Release-day checklist: README → regenerate DOCKER_HUB.md → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag.
- **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to `latest`. Each build-time install step reads the `/releases/latest` Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major pin), `DEBIAN_VERSION=trixie-slim` (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag. - **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to `latest`. Each build-time install step reads the `/releases/latest` Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major pin), `DEBIAN_VERSION=trixie-slim` (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag.
- **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`. - **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`.
- **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`. - **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.