docs, ci: add spec and package changelogs with a CI check - #300
Merged
Merged
Conversation
Contributor
|
gnidan
force-pushed
the
docs-changelog
branch
from
September 17, 2026 04:51
8ac6db8 to
ed6d678
Compare
CHANGELOG.md at the repository root records changes to the schemas under schemas/. The schemas ship inside @ethdebug/format, so the file is keyed by that package's version. Each entry gives a summary and the pull request, then three sub-items: the schemas the change touches, what it means for producers, and what it means for consumers. The producer and consumer lines each start with one of three fixed prefixes: - "no change needed." when nothing valid becomes invalid or changes meaning for that party - "optional:" when the change adds a capability that obliges nobody - "required:" when earlier valid output stops validating, the specification adds a must, or the meaning of valid data changes; the line names the keyword or prose that imposes the obligation An impact line states the net effect for a party that moves from the previous published version to the version of its section. A change inside a schema that is new in that version obliges nobody, and an obligation that a later change in the same version reverses does not appear. Sections are only Added and Changed; they do not signal obligations, the prefixes do. The file has an entry for every pull request that changed schemas/ between the 0.1.0-0 publication and the 0.1.0-1 tag, each checked against the schema trees of those two versions, and an Unreleased section for the changes merged since (#284, #286).
The page at /spec/changelog imports the root CHANGELOG.md, so the
site and the repository always show the same text. The file must stay
valid MDX: no HTML comments, and no bare "<" or "{" outside code.
Each of the seven public packages gets a CHANGELOG.md keyed by its own version, because the packages are versioned independently. Entries describe changes that a user of the package can see. @ethdebug/format and @ethdebug/pointers were on npm at 0.1.0-0, so their files carry the history from that publication to 0.1.0-1, reconstructed from a comparison of the published tarballs. The other five packages were first published at 0.1.0-1.
npm always includes package.json, README* and LICENSE* in a tarball, but not CHANGELOG.md. Each public package now lists the file in "files", and the tarball allow-list in bin/packlist.ts accepts CHANGELOG* so that bin/check-tarballs.ts does not reject it.
bin/check-changelog.ts compares a pull request with its base branch. It fails when the diff changes schemas/ without the root CHANGELOG.md, or changes the src/, bin/ or package.json of a public package without that package's CHANGELOG.md. Colocated test files do not count. The label "changelog: skip" exempts a pull request. The job has its own workflow that also runs on "labeled" and "unlabeled" events: Actions cannot filter those events by label name, so in ci.yml each label change would run the whole suite again.
Each "Producers:" and "Consumers:" sub-item in the root CHANGELOG.md must start with "no change needed.", "optional:", or "required:", and each section heading must be "Added" or "Changed". The check reads the file on every run, whether or not the diff changes schemas/, and reports each problem with its line number. The bullets in the intro that describe the sub-items are not sub-items, and the check ignores them.
Before the version bump, the operator renames "## Unreleased" to the new version and date in the root file and in the file of each package that Lerna will bump, and leaves an empty Unreleased heading above it. "yarn lerna changed" shows which packages those are. A package that is bumped only because a dependency changed gets one "Changed" entry that names the dependency, so that each published version has a section of its own. In the root file the operator also reconciles the Unreleased entries against the previous published version, because the impact lines state the net effect between published versions.
gnidan
force-pushed
the
docs-changelog
branch
from
September 17, 2026 05:24
ed6d678 to
9eb4665
Compare
This was referenced Sep 17, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The format gets a changelog, and so does each published package.
CHANGELOG.mdat the repository root records changes to the specification, keyed by the@ethdebug/formatversion. Entries are grouped as Added or Changed, name the schemas they touch, link the pull request, and carry aProducers:line and aConsumers:line for an emitter such as solc and a reader such as a debugger. Each of those lines starts with one of three fixed prefixes:no change needed.,optional:for a new capability that obliges nobody, orrequired:when earlier valid output stops validating, the spec adds a must, or the meaning of valid data changes. Arequired:line names the schema keyword or the prose that imposes the obligation. Each line states the net effect for a party that moves from the previous published version to the version of its section, so a change inside a schema that is new in that version obliges nobody, and an obligation that a later change in the same version reverses does not appear. The sections do not signal obligations; the prefixes do. Every line in the0.1.0-1section was checked against the schema trees at0.1.0-0and at the0.1.0-1tag. The file is backfilled with an entry for every pull request that changedschemas/between the0.1.0-0publish in July 2024 and the0.1.0-1tag, and it has an Unreleased section with the two spec changes merged since (#284, #286). The docs site renders the same file at/spec/changelog.Each of the seven public packages gets a
CHANGELOG.mdof its own, keyed by that package's version, in the same shape without the impact lines.@ethdebug/formatand@ethdebug/pointerswere already on npm at0.1.0-0, so their files carry a real history back to that first publication, reconstructed by comparing the published tarballs; the other five were first published at0.1.0-1, and that release's entry says so. npm includespackage.json,README*andLICENSE*whateverfilessays, but notCHANGELOG.md— each package therefore listsCHANGELOG.mdinfiles, and the tarball allow-list accepts it.A new
changelogjob in CI fails a pull request that changesschemas/without touching the root changelog, or that changes a public package'ssrc/,bin/, orpackage.jsonwithout touching that package's changelog. Colocated test files do not count. The labelchangelog: skipexempts a pull request, and the job lives in its own workflow that also triggers onlabeledandunlabeled, so that applying the label re-runs this check and nothing else. The same script lints the root file: aProducers:orConsumers:line that does not start with one of the three prefixes fails the job, and so does a section heading other than Added or Changed. RELEASING.md gains the release-time step: rename Unreleased to the new version and date in the root file and in every bumped package's file before the bump, leaving a fresh empty Unreleased heading above it, and reconcile the root file's Unreleased entries against the previous published version.Related: #288 will add an entry with
required:lines for both producers and consumers to the Unreleased section when it lands; the upstream coordination for it is tracked in #287. The release-time changelog step extends the runbook from #298.