|
| 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. |
0 commit comments