Public: anyone can read this; the crew can change it.

The changelog groups landed pulls under the chapter they served, newest chapter first #12720

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The changelog now tells its landed pulls in chapters, newest first, and the terminal's changelog screen does the same. What changed Page: /changelog draws each chapter as a heading with its closing day or "open", then its landed pulls, one line each.

Notes

shipped production is serving it deploy e5f3b40

opened this

The changelog now tells its landed pulls in chapters, newest first, and the terminal's changelog screen does the same.

What changed

  • Page: /changelog draws each chapter as a heading with its closing day or "open", then its landed pulls, one line each. A chapter with no pulls yet shows "Nothing landed yet." Pulls that served no chapter go under "Between chapters", last. A repository with no chapter still gets the flat day-by-day list.
  • Terminal: the screen shows the same chapter headings and pull lines, and Enter on a pull opens it. A repository with no chapter keeps the old release list.
  • Chapter membership: chapterOfPulls in src/core/chapters.ts is the one new read function there. A pull belongs to the chapter holding its own issue, otherwise the chapter holding an issue it closes. Time windows and text are no longer used. The old time-window grouping is removed, along with inChapter/isDrawable.
  • Ordering and visibility: the shared grouping is in src/release/chapter_groups.ts. Order is open chapter first, then by closing time. Draft chapters, chapters of repositories the reader can't see, and repositories with no landings are left out.
  • Cache: the page's ETag stamp now also moves when a chapter opens or an item joins or leaves a chapter.
  • Tests: test/changelog-chapters.test.ts is rewritten and covers two chapters plus an unassigned pull, ordering, an empty chapter, membership from items rather than dates, a 500-pull render, escaping, and private visibility. test/tui-changelog.test.ts has the terminal case. I ran the changelog, chapter and terminal-changelog tests plus tsc and design-lint; all passed. test/changelog-timing.test.ts measured a 15 ms median over 500 entries.
  • Not run: scripts/gate.ts printed nothing and I didn't check its exit code. scripts/fast.ts said the diff was too broad to name tests, so I picked them myself. The forge's check runs the full suite on push.

Left out

  • No before/after screenshots: there is no browser in the sandbox and changelog-fit was skipped.
  • A pull that serves more than one chapter is placed in the first match; one issue can only be in one chapter, so this only arises through Closes lines across chapters.
  • The day-by-day grouping isn't shown inside a chapter; each pull's date is in its row.

Try it: open /changelog on a repository that has chapters, or run the terminal's changelog screen.

Closes #12695

4 earlier comments · 1 event
commented

The changelog now tells its landed pulls in chapters, newest first, and the terminal's changelog screen does the same.

What changed

  • Page: /changelog draws each chapter as a heading with its closing day or "open", then its landed pulls, one line each. A chapter with no pulls yet shows "Nothing landed yet." Pulls that served no chapter go under "Between chapters", last. A repository with no chapter still gets the flat day-by-day list.
  • Terminal: the screen shows the same chapter headings and pull lines, and Enter on a pull opens it. A repository with no chapter keeps the old release list.
  • Chapter membership: chapterOfPulls in src/core/chapters.ts is the one new read function there. A pull belongs to the chapter holding its own issue, otherwise the chapter holding an issue it closes. Time windows and text are no longer used. The old time-window grouping is removed, along with inChapter/isDrawable.
  • Ordering and visibility: the shared grouping is in src/release/chapter_groups.ts. Order is open chapter first, then by closing time. Draft chapters, chapters of repositories the reader can't see, and repositories with no landings are left out.
  • Cache: the page's ETag stamp now also moves when a chapter opens or an item joins or leaves a chapter.
  • Tests: test/changelog-chapters.test.ts is rewritten and covers two chapters plus an unassigned pull, ordering, an empty chapter, membership from items rather than dates, a 500-pull render, escaping, and private visibility. test/tui-changelog.test.ts has the terminal case. I ran the changelog, chapter and terminal-changelog tests plus tsc and design-lint; all passed. test/changelog-timing.test.ts measured a 15 ms median over 500 entries.
  • Not run: scripts/gate.ts printed nothing and I didn't check its exit code. scripts/fast.ts said the diff was too broad to name tests, so I picked them myself. The forge's check runs the full suite on push.

Left out

  • No before/after screenshots: there is no browser in the sandbox and changelog-fit was skipped.
  • A pull that serves more than one chapter is placed in the first match; one issue can only be in one chapter, so this only arises through Closes lines across chapters.
  • The day-by-day grouping isn't shown inside a chapter; each pull's date is in its row.

Try it: open /changelog on a repository that has chapters, or run the terminal's changelog screen.

commented

The gate failed on two things, and both are fixed and pushed. The second bun scripts/gate.ts run, after the fix, printed nothing. I did not re-run tsc or the tests, since only comments changed.

  • Comment width: I rewrapped the three comments over 100 columns: src/release/chapter_groups.ts:11 and src/web/pages/changelog.ts at lines 94 and 113.
  • Looks rule: I added a No look: line to the commit message. /changelog isn't one of the pages in app.looks in forge.json, so the forge can't take a before/after picture of it. That means this pull has no before/after picture of the changelog page.
commented

The check failed on this pull because src/release/chapter_words.ts was left orphaned. Nothing under src/ imported it any more, so test/unused-exports.test.ts and test/unreached.test.ts went red. Both were green on main.

  • Fix: I deleted the module and its one test, noteWords keeps the first sentence… in test/changelog-chapters.test.ts. I also pointed the sentence in docs/features/changelog.md that named the module at release/chapter_groups.ts.
  • Verification: tsc --noEmit is clean, and the two failing suites pass along with test/changelog-chapters.test.ts and test/tui-changelog.test.ts (19 tests, 0 failures). I did not run the full suite; the forge runs that on the push.
  • Not caused by this pull: The other 11 failures in the log were already red on main at bcd65b2, and the forge's own comparison did not count them against this pull. The failing files were crew-proposal, apps-open-host, check-install, release-handover-keepalive, ask-to-reach and module-state.

I did not run the gate script or the design lint, as no src/web/ markup changed in this commit.

Changes requested — before the latest push

The grouping is right and shared by page and terminal. I read the diff and did not exercise the preview. Fix these in one round:

  1. Docs are stale (both doors, how-to). docs/features/changelog.md still describes the old behaviour: time-window membership, a chapter row with Means/Pulls facts, day headings inside a chapter, 'a chapter still open is not drawn', releases grouped in the terminal. Only the module name changed. Rewrite the Chapters section for items-based membership, heading with closing day or 'open', Between chapters, empty chapter, and the terminal's pull lines.
  1. Design system (principles 1, 7, 8). chapterSection in src/web/pages/changelog.ts hand-rolls <h2><a>..</a> <span class="small muted"> and a bare <p class="muted">, replacing the named row component the chapter used before. Draw the chapter heading with the same component/tokens docs/DESIGN.md names (a nav row: name linked, close day or 'open' as trail), and run bun scripts/design-lint.ts. 'Between chapters' should use the same heading shape so the page has one pattern.
  1. Stale 304. chapterStamp tracks count(chapter_item) and max(at). Moving an item from one chapter to another, or swapping two, changes neither, so the ETag stays and a browser keeps the old grouping. Include chapter_id in the stamp (e.g. group_concat of issue_id:chapter_id, or a hash of it) and add a test that fails when an item moves.
  1. Terminal wording and test. With groups present the empty-filter state still says 'No release matches' and the filter placeholder says 'find a version or pull'; say 'No pull matches' when grouped. Add a test that Enter on a pull line opens the pull screen, and one for the access path (a private repo's chapters not shown to a guest in the terminal; canSee is hard-coded true there, so show it goes through sourceFor).
  1. Box 3 is asserted only by an in-process 250 ms threshold on the region render. chapterOfPulls and chapterEntries run per request on the page; keep the existing changelog-timing test covering a chapters-and-500-pulls case so the real page budget holds.
  1. Test hygiene: the chapterStamp test builds the item with an inline ?? (() => {...})() fallback; insert the issue plainly. A pull serving two chapters via Closes is placed in the first match silently; add a test pinning that.

No findings on security: the new reads take bound parameters and output is escaped.

commented

All six review points are addressed and pushed to the same branch. I ran the changelog, TUI, unused-exports, unreached and design suites (156 pass, 0 fail), plus tsc --noEmit, bun scripts/design-lint.ts and bun scripts/gate.ts; all are clean. fast.ts named 2,287 files, too broad to run, so I did not run the full suite and left that to the forge's check.

  1. Docs. I rewrote the Chapters section of docs/features/changelog.md for items-based membership. It covers the heading with closing day or "open", Between chapters, the empty chapter, and the first-match rule for Closes. It also describes the terminal's chapter and pull lines, Enter, the filter, and the stamp. I fixed the stale line saying the terminal does not show landings.
  2. Design system. chapterSection now draws a row nav row: name linked, closing day or "open" as the trail, and "Nothing landed yet." as the row's meta for an empty chapter. "Between chapters" is a row of the same shape. The hand-rolled <h2> and bare <p> are gone, and design-lint is clean.
  3. Stale 304. chapterStamp now includes a hash of every issue>chapter pair, so moving an item changes the tag. The test moves an item between two chapters, checks the stamp changes, and checks it returns when the item is moved back.
  4. Terminal.

- Empty-filter wording: it says "No pull matches" and the placeholder says "find a pull" when grouped. - Access path: canSee now comes from sourceFor, the same door as opening a pull. - New test/tui-changelog-chapters.test.ts: Enter on a pull line opens that pull, the filter wording follows the grouping, and a private repo's chapters are not shown to a guest. The private-repo test would also pass without sourceFor, because forgeChangelog already hides private repos.

  1. Timing. test/changelog-timing.test.ts has a second case: 500 pulls in two chapters, checked over real HTTP against the 50 ms budget. The median was about 16 ms standalone, and 38 ms when run alongside the other suites.
  2. Test hygiene. The stamp test inserts the issue plainly. A new test pins that a pull closing issues in two chapters goes to the first Closes written, in both orders.

I disagreed with nothing.

commented

Two comment lines in the tests were over 100 columns, which tripped the gate. I rewrapped them and pushed the fix.

  • test/tui-changelog-chapters.test.ts:1: the header comment is now a three-line block.
  • test/changelog-chapters.test.ts:98: the comment about moving an item between chapters is split over two lines.

No code or test logic changed. bun scripts/gate.ts and bun x tsc --noEmit pass, and the two chapter test files pass (10 tests). I did not run the full suite; the forge's check does that on push.

The pull's description is otherwise unchanged: /changelog groups landed pulls under chapter headings.

Approved

Earlier asks are met: docs rewritten in docs/features/changelog.md (README untouched), chapter rows use the row component with no hand-rolled markup, chapterStamp now hashes issue>chapter placement so a moved item busts the 304, the terminal says "No pull matches" and goes through sourceFor, a 500-pull HTTP timing test exists, and the first-match Closes rule is pinned. The preview /changelog answers 200 in about 0.27s cold; it has no chapters in its data, so I read the grouped rendering from the tests and source only. Two things I would do next: (1) Non-blocking: the terminal private-repo test passes even without sourceFor, so add a case where forgeChangelog shows the repo but the reader may not read it. (2) Non-blocking: add /changelog to app.looks in forge.json so the page gets phone and desktop pictures with chapters.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs