Repository navigation
Description
@r0ny123 suggested adopting keep-a-changelog, and the decision is yes — for SMDA and for MCRIT, so the two stay consistent. What is open is the fine tuning, and a few of those choices are load-bearing rather than cosmetic. Opening this for your input on the six below before anything is written.
Why, in one paragraph
Not the formatting. The Unreleased section. Right now #319 exists as a long-lived draft PR purely because there is nowhere to accumulate entries, and you declined to touch CHANGELOG.md in #311 for exactly that reason — "its entries are per released version and there is no unreleased section, so adding one means choosing a version number, and that is yours." The consequence is that every changelog line gets written by one person at release time, reconstructed from merge commits days later. That is the "commit log diff" anti-pattern the spec warns about, done by hand. With an Unreleased section each PR writes its own line at merge time, while whoever made the change still remembers the caveat.
1. History: don't convert it
192 entries going back to 2018-07-01. Converting them is large, low-value, and translation loses nuance.
Proposal: start the new format at [Unreleased], and put everything from v4.5.1 down under a final ## Older releases heading, verbatim. The spec's "an entry for every version" is still satisfied — they are all still there, just in the old one-line shape.
While we are in there, three genuine filing errors that the strict format would surface anyway:
v1.0.0 (2018-07-01) is filed at line 186, above the v1.9.16–v1.9.11 block |
plainly misfiled; belongs at the bottom |
v4.4.0 (2026-07-26) listed above v4.3.11 (2026-07-28) |
legitimate — a patch on an older line released after the newer minor |
v3.1.0 (2026-05-26) above v3.0.2 (2026-06-01) |
same |
Only the first is a mistake. But the last two force a decision: order by version or by date? The spec says latest first without saying which. I lean version order with the real date kept, since that is what a reader of a maintenance release expects.
2. Do NOT claim semver — this is the one I would get wrong by default
The keep-a-changelog header template asserts adherence to Semantic Versioning. SMDA does not follow it, and saying so would be a false claim rather than an aspiration:
- v4.3.4 (patch) — "Added a default-off x64 PE pass (
USE_PE_X64_PDATA_ENDS)". A new feature in a patch bump. - v3.0.2 (patch) — added
MAX_FUNCTION_CANDIDATESandMAX_CALL_REFS_PER_CANDIDATEconfig options. - v4.4.3 (patch) — the whole audit-hardening pass:
tyin CI, ~36 Hypothesis fuzz tests, 15 property tests. - v4.0.0 (major) — "Support for Aarch64!", which is an addition, not a break.
- And v4.5.1, in flight right now, ships a default flip (
USE_MACHO_ADDRESS_REF_CANDIDATESFalse→True, which changes recovery output on Mach-O with no caller action) and a serialized shape change (binweight's class default0→0.0) — both at least minor under strict semver.
So the pattern is: major = a big new capability, minor = a notable feature group, patch = everything else including small features. That is a release counter, not semver.
The good news is that SMDA already has a real compatibility contract, it just is not the package version. Three separately-versioned constants carry it, and they are what downstream actually reads:
SmdaConfig.ESCAPER_DOWNWARD_COMPATIBILITY = "4.4.5"
SmdaFunction.INTEL_PIC_HASH_ESCAPE_VERSION = [4, 3, 5]
SmdaFunction.CIL_PIC_HASH_ESCAPE_VERSION = [4, 3, 8]
Proposal: state the scope explicitly in the header instead of claiming semver — something like "the package version is a release counter; the compatibility promise for report consumers is carried by ESCAPER_DOWNWARD_COMPATIBILITY and the *_PIC_HASH_ESCAPE_VERSION markers, and by the toDict() report shape." That is both true and more useful to MCRIT than a semver badge would be.
3. Grouping: the two axes are orthogonal, and I would keep both
SMDA groups by subsystem (Recovery (intel), Recovery (AArch64), Synthesis, Docs, Housekeeping). The spec groups by change type (Added / Changed / Deprecated / Removed / Fixed / Security).
Mapped literally, six subsystem sections collapse into mostly Fixed, and the per-backend filter — the most useful one for this project — is lost.
Proposal: spec headings, subsystem as a bold prefix per bullet.
### Fixed
- **(intel)** Keep the switch index tied across a relative dispatch's base add …
- **(aarch64)** Stop recording a branch target as an inbound call reference …4. A seventh section for the compatibility notice
Recovery output moves on binaries these paths touch: is the most consumer-relevant thing in a SMDA entry — it is the warning that stored reports will differ — and the spec has no slot for it. Changed under-sells it.
Proposal: keep it as a custom ### Compatibility section, last in each release. The spec tolerates deviation, and this one earns it.
5. The convention that actually preserves the depth
This is the one worth agreeing at the same time as the format, or the structure will arrive and the substance will quietly drain out.
The format will not preserve depth by itself. SMDA's entries are unusual precisely because they carry the measurement, the caveat and the failure mode — the v4.5.1 entry is ~2,700 words and explains why GCC padding merges two functions, not just that it was fixed. Terse bullets under ### Fixed would lose all of that.
Proposal: a bullet is a summary line plus optional attached lines:
### Fixed
- **(intel)** Keep the switch index tied across a relative dispatch's base add. `_findJumpTableSize`
read the base `add` as a redefinition and sized a 27-case table at 2, so 25 unreferenced case bodies
reached the gap scan and five were booked as functions inside the function they belong to.
*Measured:* 140 built C/C++ cells (117,654 truth functions) — 20 false positives removed, no true
positive lost, 135/140 cells bit-identical. *Reproduced by reviewer on bundled fixtures.* (#306)Two rules I would like to write down with it:
- Any accuracy or performance claim names the corpus it was measured on. A bare percentage is not an entry.
- Say whether the figure was reproduced. v4.5.1 already distinguishes figures measured on our tree from figures that rest on your corpora because no bundled fixture reaches them (fix(aarch64): read the BTI target type, and resume past a refused pad's block #310's
bti jsplit, perf(aarch64): refuse a gap candidate the ARM64 PE unwind data places inside a routine #312's ARM64 PE result — tracked in Follow-ups from the open-PR review pass that are not nits #322). That distinction is worth making permanent rather than ad hoc.
6. Timing: after v4.5.1, not as part of it
#319 is written, reviewed and green in the current format. Converting it now means reviewing the release content and the format change together, and if either goes wrong the release slips.
Ship v4.5.1 as-is, then adopt against an empty Unreleased. That also gives the cleanest possible demonstration: the first things that section holds are #299's and #300's entries, written by you, in your words, at merge time — which is the entire point of the change.
Rollout, once the six above are settled
docs(docs)PR: new header and scope statement,## [Unreleased]with the standard subsections,## Older releasesover the existing 192 verbatim, fix thev1.0.0misfiling.- Update
AGENTS.md:117, which documents the current* YYYY-MM-DD: vX.Y.Z - <summary>format, and add "moveUnreleasedto the new version, add the date and the compare link" to the release checklist. - Compare links only for tagged releases — there are 11 tags for 192 entries, so they reach back to v4.4.4 and no further. Not worth backfilling tags for this.
- Optional, later: generate the GitHub release body from the section at tag time. There is no release automation at all today, so this would be new rather than a change.
@r0ny123 — items 1 (version vs date ordering), 3 (grouping), 4 (the compatibility section) and especially 5 (the depth convention) are where your input would be most useful. You write most of these entries' source material, so the convention has to be one you would actually want to follow.
Activity
chore: format the v4.5.1 entry as a nested list
chore: cut v4.5.1 (#319)
r0ny123 commentedon Sep 10, 2026
Agreed on all six, and the ordering call in 1 is right. Four things I would add, one of which I think is load-bearing and is not in the list.
1 — version order, with a sentence saying so
Version order is right, and the reason to write down why is that the two legitimate cases look like the misfiling you are fixing in the same pass. A reader who does not know that v4.3.11 is a patch on an older line than v4.4.0 sees three inversions, learns one was a mistake, and has no way to tell which. One line at the top of
## Older releases— entries ordered by version, so a patch on an older line can sit below a minor released before it — costs nothing and stops the next person "fixing" it.Version order is also what keeps the compare links monotonic once they exist, which is the other half of the argument.
2 — the constants need a rule, or naming them in the header does not help
Naming
ESCAPER_DOWNWARD_COMPATIBILITYand the two*_PIC_HASH_ESCAPE_VERSIONmarkers in the header is the right call, and stating a release counter rather than claiming semver is plainly the honest option.But those three constants are not documented anywhere a consumer looks today, and pointing at them from the header makes the changelog the place they get discovered. That only works if a move in one of them always shows up. So: if a release changes any of the three, the
Compatibilitysection says which one and from what to what. Otherwise the header promises a contract that the entries do not track, which is worse than the semver badge because it looks precise.3 — fix the prefix vocabulary to the scope list we already enforce
Spec headings with a bold subsystem prefix is the right shape. The failure mode is drift:
**(intel)**,**(x86)**,**(Intel)**,**(intel/jumptables)**all arriving over six months, and the per-backend filter you are preserving stops being greppable..github/workflows/semantic-pr-title.ymlalready enforces a closed scope list —core intel aarch64 dalvik cil common utility loaders labels report ida cli profiling tests ci build docs. Reusing it verbatim as the prefix vocabulary means the prefix is the same token as the commit scope, it is already validated on every PR, and the entry can be lifted from the PR title rather than invented.4 — agreed, and it is where the constants from 2 belong
No changes beyond tying it to 2:
Compatibilityis the natural home for both "recovery output moves on these binaries" and "this constant moved".5 — the convention, plus a third rule and a length
Both of your rules are about provenance — which corpus, and whether it was reproduced. The gap is direction.
"20 false positives removed" reads as free. What makes the current entries trustworthy is that they say what it cost: no true positive lost, or −580 false positives against −53 functions, or bit-identical on the corpora it does not reach. An entry that reports only the gain is the one that will be written when a trade did happen and nobody wanted to lead with it.
So, a third rule: a measured claim states its cost, or says there was none. In practice that is usually four words, and it is the difference between a number and a result.
One more, on length. The depth is the reason to keep the entries, but a ~2,700-word release entry is also not reviewable at release time, and the parts that get skimmed are the parts that matter. I would put a soft shape on it: the summary line is one sentence, the attached block is the mechanism, the measurement and the cost, and anything past roughly six lines belongs in the PR the entry links. That keeps the failure mode and the caveat — which is what you are protecting — without the changelog becoming a second copy of the report.
The one that is not on the list: what makes the
Unreleasedsection actually get writtenThe whole case for this change is that each PR writes its own line at merge time, while the person who made it still remembers the caveat. Nothing in the rollout makes that happen. If it stays a convention, the section is empty at release time and we are back to reconstructing from merge commits — the same anti-pattern, with a nicer heading.
Two options, in order of how much I would trust them:
semantic-pr-title: a PR touchingsrc/smda/**also touchesCHANGELOG.md, skippable with a label for the cases that genuinely do not need an entry. It is a small workflow and it fails loudly and early.AGENTS.md:117.I would do 1. The reason is the same one that makes the
Unreleasedsection worth having: at release time nobody can tell that an entry is missing, because a missing entry looks exactly like a change that did not need one. Only the PR author knows, and only while the PR is open.Happy to write whichever of these you want as the follow-up PR once you have settled 1–6 — including the CI check, which is independent of the format change and could land first.
docs(docs): describe the changelog shape the entries actually use
chore: cut v4.6.0 (#334)
danielplohmann commentedon Sep 11, 2026
Settled — the six above and your four. Decisions stated in full below so the rollout PRs need no second round trip, and yes to the one that is not on the list.
1 — version order, and the sentence saying so
Yes to both, and your reason for the sentence is better than mine for the ordering: a reader who meets three inversions and learns one was a mistake has no way to tell which. One line at the top of
## Older releases— entries are ordered by version, so a patch on an older line can sit below a minor released before it.v4.4.0overv4.3.11andv3.1.0overv3.0.2stay where they are with their real dates; only thev1.0.0misfiling moves.2 — the constants rule: adopted as you state it
If a release moves
ESCAPER_DOWNWARD_COMPATIBILITY,INTEL_PIC_HASH_ESCAPE_VERSIONorCIL_PIC_HASH_ESCAPE_VERSION, that release'sCompatibilitysection names which one and from what to what.Your framing is the load-bearing part: a header pointing at three constants that the entries do not track is worse than the semver badge, because it looks precise. The rule is what turns the pointer into a promise.
3 — the scope list as prefix vocabulary: yes, verbatim
core intel aarch64 dalvik cil common utility loaders labels report ida cli profiling tests ci build docs— the seventeen fromsemantic-pr-title.yml, no additions here.The binding rule: the prefix is the PR title's own scope token. The action does not require a scope, so a PR that carries none gets no prefix rather than an invented one. That keeps the "lift it from the title" property you are after, and it means a scope added to the workflow list is available to the changelog the same day. One vocabulary, enforced in one place.
4 — the Compatibility section: yes, and it is where 2 lands
Both kinds live there, last in each release: "recovery output moves on binaries these paths touch", and "this constant moved, from X to Y".
5 — the cost rule and the length: both yes
A measured claim states its cost, or says there was none. Adopted, and of the three rules it is the one I would least want to lose — provenance tells a reader where a number came from, direction tells them whether to believe it is good news.
One clause I want to add to it, from your own correction in #322 rather than from me. You separated a split that is a property of an instruction encoding, and does not decay, from an absolute count that is a property of everything else in the engine on the day it was taken —
bti j's 803/0 reproducing while the same toggle's 2,941 removed became 745 against a baseline 6.5 points higher. So: a figure that is marginal against a moving baseline says so. In practice that is "measured on<tree>", four words again, and it is what stops the next reader treating a stale count as a contradiction.The soft six-line shape: yes. The summary line is one sentence, the attached block is mechanism, measurement and cost, and past roughly six lines it belongs in the linked PR.
The one not on the list — option 1, and it lands first
Your reasoning settles it: at release time a missing entry looks exactly like a change that did not need one, and only the author knows which it is while the PR is open.
Specifics so you do not have to guess at them:
pull_request, notpull_request_target— it needs the changed-file list and no secrets, so a read-only token on a fork PR is enough.src/smda/**, and is satisfied by touchingCHANGELOG.md. File-level only, deliberately: a PR that edits an older entry rather thanUnreleasedpasses, and that is an acceptable false negative for a check whose job is to be loud rather than clever.no-changelog. I will create it, so the workflow can reference it as it stands.src/smda/**, so it needs none either.What moved underneath this while you were writing
v4.6.0 shipped last night in the old format, deliberately. Point 6's own timing rule was to adopt against an empty
Unreleasedso the first entries are written by their authors at merge time, and v4.6.0 could not be that — #299's and #300's entries were being written at release time either way. Adopting now means the inaugural section fills itself from #327, #329 and #335, which is a better demonstration than v4.6.0 would have been. It was also the moment three of your four additions were still unsettled, one of which rewrites every heading prefix.Two things from that release that bear on this: the entry was trimmed to ~2,200 words with a per-topic PR link on each block, which is your six-line shape arriving a release early, and those are the first links of any kind in the file. And
AGENTS.md:117now describes the nested**Topic:**list rather than the old one-line header — your rollout step 2 supersedes it, so do not read it as still documenting the shape you saw.One addition to that step while you are in there: tag after green. v4.6.0's tag was created at merge, before master's CI had confirmed the merged tree. Moving a tag nobody has fetched is cheap; moving one after a PyPI publish is not. The checklist should say the tag waits for master's CI on the release commit.
So: the CI check first, then the
docs(docs)PR against an emptyUnreleased. v4.7.0 will be the first release written the new way, and #327, #329 and #335 are its content.docs(docs): keep the tier figures from going stale
build(tests): give the slow tier an entry point (#340)