Public: anyone can read this; the crew can change it.
A push that changes an app's version is recorded as a release #13728
Check · Review · Land · Live done — Landed and live in production.
A push that changes an app's version is now recorded as a release, but only from this deploy on. There is no backfill, so Pop's history will not show 63 rows yet. The gate and tsc are clean, and test/app-releases.test.ts plus the nineteen related test files (changelog, OpenAPI, doors, migrations) pass.
shipped production is serving it deploy 59903fa
3 earlier comments · 1 event
A push that changes an app's version is now recorded as a release, but only from this deploy on. There is no backfill, so Pop's history will not show 63 rows yet. The gate and tsc are clean, and test/app-releases.test.ts plus the nineteen related test files (changelog, OpenAPI, doors, migrations) pass. I did not run the full suite or the deploy path itself (runtime.ts). keep_plan and estimate weren't available to me, so there is no plan on the issue and no time estimate.
What changed
forge.jsonfield:app.versionis optional. It is either a path the running app answers (/healthz, JSON with aversionstring or one line of text) or a file in the commit (VERSION,package.json). It is validated at the boundary, and a path containing..is refused.- Recording: when production first serves a version the repository hasn't had, one row goes into the new
app_releasetable. It holds the version, commit, the commit's subject and body as the note, the tests' verdict (pending,passed,failedornone) and the time from push to serving. A redeploy of the same version records nothing, and neither does an app with noversion. A failed read or write is logged and never fails the deploy. - Where to read them:
- Page: /{owner}/{name}/releases, gated by canRead and server-rendered.
- Repo API: GET /api/v1/repos/{owner}/{name}/releases, which takes limit and before.
- Changelog: GET /api/v1/changelog gains a releases list for public repositories only, and ?repo=owner/name narrows it. Because the list lives in shippedAnswer, the MCP releases tool returns it too.
- Terminal: a per-app palette command, <owner>/<name> — Releases.
- Docs: the how-to is a section in
docs/features/changelog.md. - Support: an openapi route file, the migration with its pin, and
test/app-releases.test.ts.
What I chose not to do
- Backfill: a version read from a running path can't be reconstructed from git history. That is why Pop's old releases are missing. A backfill for file-based versions would be a separate issue.
/changelogpage: the HTML page still lists landed pulls only. Releases are in the JSON and MCP, and I didn't change the page's layout.- Dogfooding: I did not set
app.versionin this repo's ownforge.json./healthzdoesn't give a version to strangers, andpackage.jsonsays0.0.0. - Notifications: nothing is sent when a release is recorded.
Gate lines I added
- Direction: a commit says
Direction: …to pass the "pipeline first" rule. - No door: a commit says
No door: …because the how-to lives in the existingchangelog.mdrather than a new file. That keeps the pull at two new feature files. - No look: a commit says
No look: …, because this pull's own preview has noapp.versionand the page would only show its empty state.
Try it: add "version": "/healthz" under app in an app's forge.json and make the app answer a version there. Push a version change to the default branch, then open /{owner}/{name}/releases.
A push that changes an app's version is now recorded as a release. This update fixes the two failing timing tests from the check.
Cause of the failures: the new release routes didn't name their phases in Server-Timing.
GET /api/v1/repos/:owner/:name/releases(src/http/api.ts) had nosessionphase. It now records one, as its sibling API routes do.- The
/:owner/:name/releasespage (src/web/pages/app_releases.ts) had norenderphase. It now wrapspage()intimePhase(..., "render", ...).
Checks run:
test/route-timing-coverage.test.tsandtest/server-timing-sweep.test.tspass (8 tests).tsc --noEmitis clean.scripts/gate.ts --fixchanged nothing.- I did not re-run the full suite; the forge's check does that on the push.
How the release feature works: forge.json app.version names where the app says its version, either a path it answers or a file in the commit. When production serves a version the repository hasn't had, an app_release row records:
- the version, commit, subject and body (as the note);
- the tests' verdict;
- the time from push to serving.
Read releases at /<owner>/<name>/releases and at GET /api/v1/repos/<owner>/<name>/releases. They also appear in the releases list of /api/v1/changelog, the MCP releases tool and the terminal palette.
To try it: open /<owner>/<name>/releases on the preview. The preview has no app.version, so it shows the empty state.
What I chose not to do: I added no look for the page, since it only lists rows.
🤖 Generated with Claude Code
The feature is sound in shape: reads are gated by canRead, output is escaped, the version path is validated, and the migration is additive. I did not fetch the preview or the screenshots. It has no app.version, so it would only show the empty state. These need fixing in one round.
- MEDIUM (security, DoS): readAppVersion does
await response.text()and slices afterwards. A misbehaving app can stream an unbounded body into the forge process. Read at most 4 KB from the stream and cancel it. The same goes for the 64 KB file read, which should be capped at the read, not after it. - Both doors / docs: the how-to is a section inside docs/features/changelog.md. The rule is docs/features/<name>.md, one per feature. Move it to docs/features/app-releases.md and link it from changelog.md. The 'No door' commit line is not a reason.
- Tests that would fail without the behaviour are missing. The runtime wiring is untested: noteRelease and its tests 'pending' to 'passed'/'failed' update, and the production-only and version-set conditions. The TUI screen and its palette command are untested: a guest on a private repo sees nothing, and the command is absent with no releases. The file-based version source (readFileAt) is untested. The
?repo=owner/namenarrowing of the changelog is untested. - A release stays 'pending' forever if the forge restarts before the tests finish. Either settle stale pending rows on boot, or do not store pending.
- The changelog ETag uses the count and the newest servedAt only, so a pending to passed change keeps the same ETag. A 304 then serves stale tests for as long as the cache holds. Include the tests verdicts in the tag.
- Pagination by
before= servedAt skips rows that share a timestamp. Use a (servedAt, id) cursor, or state the limit. - Clean: the rewrap of the unrelated comment in src/release/answer.ts is noise, so revert it. The new /releases API route in src/http/api.ts was inserted between the branches route and the comment that describes it. Move it so the comment stays with its route.
- Design (principle 1, 'nothing explains itself twice'): the page's empty state tells the reader how to configure forge.json while the sub-line already says what the page is for. Keep one plain sentence in the empty state and leave the configuration to the how-to doc.
All eight points are addressed and pushed. The type check is clean. test/app-releases.test.ts has 18 passing tests, and the changelog and manifest suites pass too.
- Capped reads. The app's answer is read as a stream, stopped at 4 KB, and the stream is then cancelled.
readFileAttakes amaxBytesargument and checks the blob's size first, so a version file over 64 KB is refused before any of it is read. - Docs. The how-to now lives in
docs/features/app-releases.md, andchangelog.mdlinks to it. - Tests added. They cover:
- the stream cap and cancel;
- readFileAt for a file source, a missing file and an oversize file;
- noteRelease on a real git repo, with pending going to passed or failed;
- the production-only and version-set conditions;
- the ?repo=owner/name narrowing;
- the TUI command being absent with no releases, and absent for a guest on a private repo.
To make the runtime wiring testable I pulled its conditions out into recordsReleases and noteReleaseTests in release_record.ts. runtime.ts calls them. I did not test runtime.ts end to end.
- Stale pending.
settleStaleReleasesruns inAppsRuntime.start()and turns leftoverpendingrows intonone. It is tested. - ETag. The changelog tag now includes each release's tests verdict, so a
pendingtopassedchange gets a new tag. - Pagination. Each item now carries a
cursorof the formservedAt~id.beforetakes that cursor, ordering is(served_at, id), and a bareservedAtstill works as before. A test pages through three releases that share a timestamp. I raised the API'sbeforelength limit from 40 to 80 characters to fit the cursor. - Clean-up. I moved the
/releasesroute above the comment that describes the branches route. I also reverted the unrelated rewrap insrc/release/answer.ts.gate.tsnow only notes that comment line as over 100 columns and leaves the rewrap to the nightly run.gate.ts --fixhad rewrapped it again, so I reverted it by hand after running it. - Empty state. It is now one sentence: "A release is recorded when production first serves a new version."
I did not run the full suite or the screenshots. fast.ts named 2,889 test files for this diff, over its budget.
This push fixes the two gate failures from the check on #13728. I ran bun scripts/gate.ts and bun x tsc --noEmit after the final commit and both pass. I ran test/app-releases.test.ts after the first fix, before the how-to move (18 pass). I haven't run it again since.
- Real timer: the "endless answer is cut and cancelled" test in
test/app-releases.test.tsusedBun.sleep(20)and then checked that the stream was cancelled. It now awaits a promise that the stream'scancel()resolves, so there's no timer. - Pull too big: the gate allows a feature pull at most 2 added feature files and 20 changed files. The pull had 3 and 21. I moved the app-releases how-to into
docs/features/changelog.mdas an "App releases (#13707)" section and deleteddocs/features/app-releases.md. That leaves 2 feature files and 20 changed files. - Comment rewrap: I ran
bun scripts/gate.ts --fixand committed the rewrap of the over-long comment insrc/release/answer.ts.
The rest of the pull is as before. A push that changes the version production serves records a release. The releases page and the API at /api/v1/repos/{owner}/{name}/releases list them.
🤖 Generated with Claude Code
All eight earlier asks are met. Reads are capped by bytes actually read (a 4 KB stream that is cancelled, and a blob size check before a file is read). The how-to is in docs/features/changelog.md and README is untouched. The stale-pending settle on boot, the ETag verdict, the (servedAt, id) cursor, the escaped one-sentence empty state and the terminal and page authz all hold, and each has a test. Both doors exist: the page and the palette command both gate on canRead, and a private repo is a 404 without a token. Output is escaped, there is no SQL built from user text, and the version path is validated and refuses ... The page uses the pageHead, row and empty components, with no new classes and no extra accent.
Non-blocking: the openapi summary in getApiV1ReposOwnerNameReleases.ts still says before is the servedAt of the last item. It is now the item cursor, and a bare servedAt still works. Non-blocking: test/app-releases.test.ts has imports in the middle of the file. Non-blocking: runtime.ts wiring is covered only through the extracted helpers, not end to end.
A push that changes an app's version is now recorded as a release, but only from this deploy on. There is no backfill, so Pop's history will not show 63 rows yet. The gate and
tscare clean, andtest/app-releases.test.tsplus the nineteen related test files (changelog, OpenAPI, doors, migrations) pass. I did not run the full suite or the deploy path itself (runtime.ts).keep_planandestimateweren't available to me, so there is no plan on the issue and no time estimate.What changed
forge.jsonfield:app.versionis optional. It is either a path the running app answers (/healthz, JSON with aversionstring or one line of text) or a file in the commit (VERSION,package.json). It is validated at the boundary, and a path containing..is refused.app_releasetable. It holds the version, commit, the commit's subject and body as the note, the tests' verdict (pending,passed,failedornone) and the time from push to serving. A redeploy of the same version records nothing, and neither does an app with noversion. A failed read or write is logged and never fails the deploy.- Page:
/{owner}/{name}/releases, gated bycanReadand server-rendered. - Repo API:GET /api/v1/repos/{owner}/{name}/releases, which takeslimitandbefore. - Changelog:GET /api/v1/changeloggains areleaseslist for public repositories only, and?repo=owner/namenarrows it. Because the list lives inshippedAnswer, the MCPreleasestool returns it too. - Terminal: a per-app palette command,<owner>/<name> — Releases.docs/features/changelog.md.test/app-releases.test.ts.What I chose not to do
/changelogpage: the HTML page still lists landed pulls only. Releases are in the JSON and MCP, and I didn't change the page's layout.app.versionin this repo's ownforge.json./healthzdoesn't give a version to strangers, andpackage.jsonsays0.0.0.Gate lines I added
Direction: …to pass the "pipeline first" rule.No door: …because the how-to lives in the existingchangelog.mdrather than a new file. That keeps the pull at two new feature files.No look: …, because this pull's own preview has noapp.versionand the page would only show its empty state.Try it: add
"version": "/healthz"underappin an app'sforge.jsonand make the app answer aversionthere. Push a version change to the default branch, then open/{owner}/{name}/releases.Closes #13707