Skip to content

Commit 47ae711

Browse files
cristianocclaude
andcommitted
Render review pages from structured commit messages
A commit record is a commit message whose prose sections and git trailers answer the questions reviewers of this repository ask on pull requests: which layer changed, the changelog category and entry, the generated JavaScript before and after, formatter, marshaled-format, PPX and editor effects, error-catalog rows, tests and the commands that ran. .claude/skills/records/SKILL.md defines the format and links each field to the pull requests whose review threads raised it. scripts/commitRecords.js renders one card per record, checks each record against its own diff (changelog fragment, modified generated JavaScript, magic-number bumps, v0 PPX bridge fixtures, ERROR_VARIANTS.md), and for a range adds a summary, a changelog draft and the files that more than one commit changes. The page is one HTML file with no script. Example (sh): node scripts/commitRecords.js --out review.html master..my-branch Changelog entry: - Add commit records: a commit message format that answers recurring review questions, and `scripts/commitRecords.js`, which renders review pages from them. https://github.com/rescript-lang/rescript/pull/XXXX Review: Does the renderer need the compiler? No: it reads git (messages, notes on refs/notes/records, and diffs) and has no dependencies. Area: scripts tests docs Changelog: internal Output: unchanged Tests: +scripts/commitRecords.test.js Ran: node --test scripts/commitRecords.test.js (2 passing); npx biome check on the two scripts (no findings); npx tsc (exit 0) Signed-off-by: Cristiano Calcagno <ccrisccris@gmail.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent aa2078e commit 47ae711

6 files changed

Lines changed: 1232 additions & 1 deletion

File tree

‎.claude/skills/records/SKILL.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: records
3+
description: Commit records and review pages for the ReScript compiler repository. Use when committing a change, when an agent reports its work, and when someone asks to review a commit, a pull request or a branch. Every commit message is a structured record that answers the questions ReScript reviewers ask; review pages are rendered from records with scripts/commitRecords.js, never written by hand.
4+
---
5+
6+
# Commit records and review pages
7+
8+
A **record** is a commit message whose body has named prose sections and
9+
whose last block is git trailers. Its fields are the questions reviewers of
10+
this repository ask on pull requests, answered before they are asked. A
11+
review page is rendered from records: one card per commit, and for a range a
12+
summary, a changelog draft and the files more than one commit changes.
13+
14+
## The record
15+
16+
```
17+
<subject: present tense, what the compiler or tool now does>
18+
19+
<one paragraph: the change at the level of the language or the tool>
20+
21+
Example (rescript):
22+
<the ReScript source that shows the change, at most 15 lines>
23+
24+
Before (js):
25+
<generated JavaScript before, for that source>
26+
27+
After (js):
28+
<generated JavaScript after>
29+
30+
Source: <how the Before/After JavaScript was produced: compiler and revision,
31+
or the snapshot file in the diff>
32+
33+
Breaking: <what existing code or tooling stops working, and the migration>
34+
35+
Changelog entry: <the exact bullet of the changes/<name>.<category>.md fragment>
36+
37+
Review: <a question a reviewer raised or will raise, and its answer; repeat>
38+
39+
Area: syntax printer frontend typechecker lambda codegen runtime rewatch
40+
analysis reanalyze gentype tools playground scripts ci docs tests
41+
Changelog: breaking | feature | fix | docs | polish | internal | none
42+
Output: unchanged | changed <which programs>, <evidence>
43+
Formatting: unchanged | changed <which source shapes>
44+
Formats: none | <bumped magic numbers: ast cmi cmt cmj>
45+
PPX: unchanged | <effect on the frozen v0 PPX wire>
46+
Editor: unchanged | <effect on completion, hover, hints; fixtures>
47+
Errors: <ERROR_VARIANTS.md rows added, removed or relinked>
48+
Tests: +added/path ~updated/path -removed/path
49+
Ran: <command and result>; <command and result>; ...
50+
Measured: <quantity before -> after, and what produced it>; ...
51+
Depends: <PRs or commits this one stacks on or conflicts with>
52+
PR: #<number>
53+
Signed-off-by: <Name> <email>
54+
```
55+
56+
- **Prose sections** are a line `Name:` or `Name (lang):` followed by text or
57+
a block indented by 4 spaces. `lang` is `rescript`, `js`, `ts`, `sh`,
58+
`rust`, `ocaml` or `text`; the renderer highlights ReScript and JavaScript.
59+
`Before` and `After` sections of one language render side by side with
60+
changed lines marked. Use `Before (rescript)` / `After (rescript)` for a
61+
formatter change and `Diagnostic (text)` for compiler output. Any other
62+
name is allowed and renders as prose or code.
63+
- **The final block is git trailers**: `Key: value` lines, continuation lines
64+
indented by one space, nothing after them. `git interpret-trailers --parse`
65+
must read every key. `Signed-off-by` (DCO) is required on every commit.
66+
- **Required keys**: `Area`, `Changelog`, `Output`. `Formatting`, `Formats`,
67+
`PPX` and `Editor` are required whenever the change touches the syntax
68+
library, the parsetree, the typed tree or Lambda. Omit the others when they
69+
do not apply.
70+
- **Wording** follows the writing rules: present facts, positive statements,
71+
claims as strong as their evidence, every number labelled by what produced
72+
it. A JavaScript `Before`/`After` pair says where it came from in a
73+
`Source:` paragraph (compiler run, or a snapshot file in the diff).
74+
- **Lists in trailers**: `Ran` and `Measured` separate items with `; `
75+
(outside parentheses); each item renders on its own line. `Output` and the
76+
other state trailers start with their state word (`unchanged`, `changed`,
77+
`none`), followed by the detail.
78+
79+
## Why these fields
80+
81+
Each field answers a question that recurs in the review threads of the
82+
upstream repository (62 merged pull requests between #8606 and #8857, human
83+
and automated review comments).
84+
85+
| Field | The question it answers | Where reviewers asked it |
86+
| --- | --- | --- |
87+
| `Area` | Which layer changed, so who reviews it and which suites apply | AGENTS.md routes by layer; AST changes broke editor analysis in #8606, #8619, #8633, #8746 |
88+
| `Changelog` + `Changelog entry` | Is it user-facing, which section, is the link right, is it short | missing in #8611, #8667, #8691, #8692, #8693, #8694; missing or wrong link in #8627, #8631, #8633, #8634, #8662; too long in #8608; breaking or internal in #8606, #8682 |
89+
| `Output` + `Before`/`After (js)` | What the generated JavaScript is now, and whether existing programs change | differential JS rebuild in #8606; byte-identical claim in #8769, #8773; JS shown in #8801; invalid to valid JS in #8692 |
90+
| `Formatting` + `Before`/`After (rescript)` | Does `rescript format` rewrite existing code, and does it round-trip | churn in production code asked in #8611; round-trip and comment loss in #8614, #8627, #8674, #8677 |
91+
| `Formats` | Does a marshaled artifact change without a magic-number bump | CMT bump asked in #8682; CMI/CMT/CMJ in #8606; Lambda tag order for `.cmj` in #8746 |
92+
| `PPX` | Does the frozen v0 wire still carry the same tree to external PPXs | `parsetree0.ml` touched in #8619; identity PPX no longer a no-op and missing ast-mapping fixture in #8606; PPX output rejected in #8682 |
93+
| `Editor` | Do completion, hover and inlay hints still work on the new nodes | #8606, #8619, #8746 |
94+
| `Errors` | Is `tests/ERROR_VARIANTS.md` in step with the fixtures | #8746 |
95+
| `Tests` | Which tests pin the change, and do they observe the claimed effect | missing coverage in #8667, #8771, #8773; assertion too weak in #8667; widths in #8677 |
96+
| `Ran` | Which suites ran | PR test plans (#8692) and replies ("syntax and roundtrip suites pass", #8674) |
97+
| `Measured` | Performance before and after, on what input | #8769, #8771, #8773, #8801 |
98+
| `Depends` | Stacking and conflicts with open PRs | #8606 (conflict with #8608), #8771, #8773 (stacked) |
99+
| `PR` | The discussion behind the change | the renderer links it |
100+
| `Signed-off-by` | DCO | the most frequent automated finding: #8691, #8729, #8773, #8837, #8842, #8846, #8857 |
101+
| `Breaking` | What stops working and how to migrate | #8606, #8634, #8682 |
102+
| `Review` | Answers given in the thread, kept with the change | #8617, #8667, #8682 |
103+
104+
## Rendering
105+
106+
```sh
107+
node scripts/commitRecords.js --out review.html <rev>...
108+
node scripts/commitRecords.js --out review.html <base>..<branch>...
109+
node scripts/commitRecords.js --fragment --out part.html <rev>...
110+
```
111+
112+
- A revision renders one card. A range renders a summary row, a changelog
113+
draft grouped by category, its commits as cards, and the files more than
114+
one commit (or more than one range) changes.
115+
- Each card checks the record against its diff: a changelog category with no
116+
new `changes/` fragment (or a `Changelog entry` that differs from the
117+
fragment's bullet), modified generated `.mjs`/`.cjs` files under
118+
`Output: unchanged` (new ones from new tests are counted, not flagged), a magic number bumped in `compiler/ext/config.ml` that
119+
`Formats` does not name, a parsetree change with no ast-mapping fixture, a
120+
new `super_errors` fixture with no `ERROR_VARIANTS.md` change. A failed
121+
check is shown on the card. The DCO app checks `Signed-off-by`.
122+
- The page is one self-contained HTML file: no script, no external data
123+
(fonts fall back to system faces), light and dark themes, phone width.
124+
`--fragment` omits the document skeleton for embedding.
125+
- A note on `refs/notes/records` replaces the commit message's record. Use it
126+
for commits that exist already (history, a squash merge) and for review
127+
outcomes added later; a new commit carries its record in its message.
128+
129+
## When to use
130+
131+
- Every commit an agent makes carries a record in its message.
132+
- An agent's report lists its commits and the rendered page; the records are
133+
the description of the work. A pull request description is a rendering of
134+
its range.
135+
- Before review or merge: render `master..<branch>` and hand over the page.

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,9 @@ relevant guidance from each.
7272
need to.
7373
- Include appropriate tests with all changes
7474
- Build must pass before committing
75+
- Write each commit message as a record in the format of
76+
[`.claude/skills/records/SKILL.md`](.claude/skills/records/SKILL.md), and
77+
render review pages from records with `node scripts/commitRecords.js`
7578

7679
### Stacked pull requests
7780

‎changes/commit-records.internal.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Add commit records: a commit message format that answers recurring review questions, and `scripts/commitRecords.js`, which renders review pages from them. https://github.com/rescript-lang/rescript/pull/XXXX

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,8 @@
6161
"changelog:preview": "node scripts/changelog.js preview",
6262
"changelog:release": "node scripts/changelog.js release",
6363
"changelog:open": "node scripts/changelog.js open",
64-
"test-changelog": "node --test scripts/changelog.test.js"
64+
"test-changelog": "node --test scripts/changelog.test.js",
65+
"test-commit-records": "node --test scripts/commitRecords.test.js"
6566
},
6667
"files": [
6768
"CHANGELOG.md",

0 commit comments

Comments
 (0)