Add changelog restructuring and website publishing proposals - #1551
Conversation
Replace the single three-stage plan with three todo files: replacing CHANGELOG.md with a changelog/ directory (P1, the merge-conflict fix), publishing the structure on the website (P4, blocked by the first), and an investigation into generating the changelog from Git history (P4). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013RUcrfUKZ3tbjGqkF5xncc
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
functionalscript | cf1b3d2 | Commit Preview URL Branch Preview URL |
Aug 14 2026, 02:41 PM |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
o2alexanderfedin
left a comment
o2alexanderfedin
left a comment
There was a problem hiding this comment.
Reviewed at 0b4c0ca2, baseline origin/main = 6d26e264. Three new todo/ files, no code. I re-derived every count, path and existential claim against the tree rather than reading them. Almost everything holds; one claim does not, and it is load-bearing for the design, so this is a comment.
The ordering claim does not reproduce
todo/changelog-directory.md line 30:
Entry ordering: PR numbers are monotonic, so sorting filenames by number descending reproduces the current newest-first order.
It does not. The current ## Unreleased section, in file order, is:
1546 1548 1548 1545 1544 1543 1542 1542 1541 1538 1539 1530 1540 1536
1537 1533 1534 1531 1527 1526 1526 1520 1520 1525 1522 1519 1516 1514
That is 28 entries with 6 adjacent ascending steps (1546→1548, 1538→1539, 1530→1540, 1536→1537, 1533→1534, 1520→1525). A stable descending sort by PR number moves 12 of the 28 entries. The very top of the file is the counterexample: #1546 sits above #1548.
The premise is the part that slips. PR numbers are monotonic in creation order, but §8.3 has the entry written and merged later — so the file's order is merge order, and a PR opened earlier can merge after one opened later. #1548 (common/monoid balanced fold) merged before #1546 (sorted_list tail policies), so #1546 is on top.
This is not cosmetic for the proposal: the release step at line 32 is "concatenate unreleased/*.md (descending) into changelog/<version>.md", so adopting the directory as written would silently reorder released sections relative to what the project produces today. Two honest ways out — say the new order is PR-number order and that this is an accepted change, or keep merge order by carrying an explicit sequence (a per-file field, or ordering by the file's own first-commit date). Either is fine; the current text just asserts the two orders coincide, and they don't.
Everything else re-derived and holding
| claim | where | verified |
|---|---|---|
CHANGELOG.md "over 2000 lines" |
directory.md:9 | 2065 |
entries go at the top of ## Unreleased |
directory.md:8 | AGENTS.md §8.3, verbatim |
AGENTS.md §8.3 is the entry workflow, §8.4 the release/version rule |
directory.md:52 | §8.3 "CHANGELOG" (L1220), §8.4 "Breaking changes and versioning" (L1249) |
CONTRIBUTING.md needs updating |
directory.md:53 | exists, and references CHANGELOG.md at L123 |
| a PR can have several entries | directory.md:26 | 4 in Unreleased alone (#1548, #1542, #1526, #1520 each twice) |
| pre-convention entries have no PR number | directory.md:39 | exactly 3 of 431 released entries lack a /pull/ link (0.6.0, 0.6.9, 0.6.11) — and the preamble already says so |
| the preamble is versioning convention + entry-style rules | directory.md:18 | CHANGELOG.md:1–20, both present |
changelog/0.44.0.md is a real target |
directory.md:37 | ## 0.44.0 at L154; 96 released sections total |
| Git stores no empty directories | directory.md:33 | correct |
| entry Markdown subset = paragraphs, list items, inline code, bold, links | directory.md:41, website.md:21 | across all 459 entries: 0 code fences, 0 tables, 0 sub-headings, 0 images, 0 blockquotes; 405 use inline code, 178 use bold, and every link target matches /pull/NNN — no exceptions |
| "the repo has no Markdown parser" | website.md:19 | confirmed — fjs/media/ has html, json, nix, rust, type, and no markdown anywhere in fjs/ |
fjs/website is the website generator |
website.md:15 | fjs/website/module.f.mjs, "Static website generation program" |
| BNF machinery available for the parser | website.md:22 | fjs/bnf/ |
the **BREAKING CHANGES:** marker drives version bumps |
git-history.md:20 | AGENTS.md §8.4, including the bump table |
Cross-links between the three files all resolve (they are co-located in todo/). node bin/linkcheck.mjs gives a broken-link set byte-identical to origin/main — 154 lines on both, diff empty — so nothing new is stranded.
Format: the three files use # Title / ## Problem, one level shallower than the template in todo/README.md, and **Blocked by:** as a relative file link rather than the template's anchor. Both match what the tree actually does (# Title is the majority in todo/, and file-link Blocked by is used throughout fjs/*/todo/), so I am not flagging it — noting only that I checked rather than assumed.
No CHANGELOG entry, correctly: §8.3 exempts PRs that only touch todo/.
Minor
changelog-directory.md is P1, which todo/README.md defines as "Blocking — nothing else can proceed". Nothing is blocked on it except changelog-website.md, which is itself P4. P1 is used sparingly in this tree — 6 real files out of 295 with a priority, and they are the Deno CI breakage, .f.js package support, the TypeScript→mjs migration, the nanvm MVP roadmap, and fjs–nanvm integration. P2 looks closer to the mark.
Review on #1551 showed the ordering claim was wrong: the current CHANGELOG is in merge order, which a descending PR-number sort does not reproduce. State the deviation as accepted — deterministic and conflict-free now, with exact merge order recoverable later by generating from Git history. Also lower the priority to P2: nothing is blocked on this, which is what P1 means in todo/README.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013RUcrfUKZ3tbjGqkF5xncc
|
Addressed in ddb2cb7, both points resolved per the review's first suggested way out:
Generated by Claude Code |
o2alexanderfedin
left a comment
o2alexanderfedin
left a comment
There was a problem hiding this comment.
Re-reviewed at cf1b3d2e, against origin/main 00f0832d. Docs-only: three files under todo/, 144 added lines, nothing else in the diff versus the merge base. Both items from the previous round are resolved.
Ordering claim — fixed, and I re-derived it against the current tree rather than reading the new wording. The proposal no longer says PR-number order reproduces today's file; it now says the file is in merge order, that descending PR-number order does not reproduce it exactly, and that the deviation is accepted. That matches what the tree shows. Parsing ## Unreleased on 00f0832d (bullets joined across their wrapped lines, PR number taken from the entry's /pull/NNN link):
- 30 entries, all linked
- 6 adjacent ascending steps:
1546<1548,1538<1539,1530<1540,1536<1537,1533<1534,1520<1525 - 15 of 30 entries change position under a descending sort
So the file is still not in PR-number order, and the release step described here would still reorder it — which is now exactly what the document says it does. The numbers differ from last round (the section has turned over since #1547/#1549/#1550 merged); I derived them fresh rather than carrying the old ones over.
Priority — fixed. P1 → P2. P2 is used by 8 files repo-wide versus 6 for P1, and this is a concrete structural proposal, so P2 sits fine.
Re-checked the claims the delta could have invalidated, since CHANGELOG.md grew by 16 lines on main:
- "over 2000 lines" — 2082
- 97
##sections, 96 released,0.44.0present, so one file per release retrofits cleanly - 461 entries, 3 unlinked, and the only two non-
/pull/links in the file are the preamble's Keep-a-Changelog and SemVer links — so "pre-convention entries have no PR number to name a file by" holds - Markdown subset: 0 fences, 0 tables, 0 sub-headings in the whole file
- Preamble does carry both the versioning convention and the entry-style rules the
changelog/README.mdbullet claims it does - No Markdown parser under
fjs/(no.mjs/.tsthere mentions one), andfjs/websiteandfjs/bnfboth exist, so the website proposal's cost estimate stands AGENTS.md§8.3 and §8.4 exist under those numbers andCONTRIBUTING.mdis presentnode bin/linkcheck.mjs— broken-link set byte-identical toorigin/main(20 lines, same entries); the three new files' relative cross-links all resolve
No CHANGELOG entry required: todo/-only under §8.3. No code touched, so no build or test gates apply.
3 participants
Summary
This PR adds three new proposal documents to the
todo/directory outlining a plan to improve the changelog management and publishing workflow for the FunctionalScript project.Changes
changelog-directory.md: Proposes replacing the single
CHANGELOG.mdfile with achangelog/directory structure to eliminate merge conflicts on concurrent PRs. Each PR would contribute its own file (changelog/unreleased/<PR>.md), which are then consolidated during releases.changelog-from-git-history.md: Proposes investigating whether changelog entries can be derived from Git history instead of being manually maintained, evaluating three potential approaches: commit-message extraction, authoring assistants, and build-time summarization.
changelog-website.md: Proposes publishing the changelog on the FunctionalScript website by extending the website generator to read the
changelog/directory and render release index and per-release pages. This is marked as blocked pending completion of the directory restructuring proposal.Implementation Details
https://claude.ai/code/session_013RUcrfUKZ3tbjGqkF5xncc