From 4cce39d16780019acb11fb270405c2585b39c7b6 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Sat, 23 May 2026 19:26:46 +0200 Subject: [PATCH] AGENTS: add 'Upstream sources' section pointing at anomalyco/opencode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tonight's v1.15.10 release surfaced a documentation drift footgun: I checked github.com/sst/opencode (a fork) for release notes instead of the canonical github.com/anomalyco/opencode. Empty bodies on sst led me to write 'upstream releases ship empty bodies and no CHANGELOG' in the v1.15.10 CHANGELOG, which was wrong — anomalyco's release pages have rich Core/TUI/Desktop/SDK sections. Added a new 'Upstream sources — where to look up release notes' section between 'Versioning scheme' and 'Critical conventions', documenting: - Canonical upstream for opencode-ai (anomalyco/opencode), pi (npm tarball CHANGELOG.md), other floated tools. - The sst/opencode trap explicitly named so future-pi doesn't repeat the mistake. - Working fetch commands as muscle memory: 'npm view ... time' for latest stable filtering, 'curl /releases/tags/' for body, 'npm pack' for pi's changelog. No CI implications, doc-only. --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f045cf1..0ad4395 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,31 @@ CI produces eight Docker Hub tags per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n] When bumping the opencode version, bump `OPENCODE_VERSION` in `Dockerfile.variant` and update the comment in `.env.example` if it names a specific model/version for context. +## Upstream sources — where to look up release notes + +When drafting a release CHANGELOG entry, pull notes from the **canonical upstream repo for each tracked package**. Getting this wrong leads to thin or wrong release notes; the image bytes are unaffected but the documentation suffers. + +| Package | Canonical upstream | What you'll find there | +|---|---|---| +| `opencode-ai` (npm) | | Per-version release notes with Core / TUI / Desktop / SDK sections, contributor attributions. Some versions have empty bodies (internal/no-user-visible); most do not. | +| `@earendil-works/pi-coding-agent` (npm) | The `CHANGELOG.md` shipped inside the npm tarball: `npm pack @earendil-works/pi-coding-agent@` then extract `package/CHANGELOG.md`. | Rich changelog with New Features / Added / Changed / Fixed sections per version. | +| Other floated tools (gosu, fzf, bat, eza, zoxide, uv, nvim, gitea-mcp, Go, oh-my-opencode-slim) | Each project's own GitHub releases page | Usually less material per release; quote selectively. | + +**Trap to avoid:** there is a `github.com/sst/opencode` repo that some search results surface; that's a fork (and probably the historical name people associate with opencode given the upstream lineage). It does NOT track the same release timeline. Use `anomalyco/opencode` for opencode release notes. + +Fetch pattern (saved here for muscle memory): + +```bash +# Latest stable opencode-ai versions on npm +npm view opencode-ai time --json | python3 -c 'import sys,json,re; d=json.load(sys.stdin); print(*sorted([(v,t) for v,t in d.items() if re.fullmatch(r"\d+\.\d+\.\d+",v)], key=lambda x:x[1], reverse=True)[:6], sep="\n")' + +# Release notes for a specific version +curl -s https://api.github.com/repos/anomalyco/opencode/releases/tags/v1.15.10 | python3 -c 'import sys,json; print(json.load(sys.stdin).get("body","(empty)"))' + +# pi changelog +cd /tmp && npm pack @earendil-works/pi-coding-agent@0.75.5 && tar -xzf earendil-works-pi-coding-agent-0.75.5.tgz package/CHANGELOG.md && head -40 package/CHANGELOG.md +``` + ## 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.