Changelog entries and the conformance workflow's lists move into files a change adds #632
Loading…
Reference in a new issue
No description provided.
Delete branch "chore/shared-append-points-files"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Why
Every change to WAI appended to the same few lines. Its changelog entry went to the head of
## Unreleasedinwai/CHANGELOG.md, and its CI went into the listswai-conformance.ymlkept by hand: the trigger's extension paths,
WAI_FEATURESand its two siblings, the binaries and teststhe verifiers' job builds first, one step per module, the features-alone loop, the integer
kernels' tests and the cargo-class corpora. Two branches open at once each added a line at
the same place, so any two of them conflicted, and they merged one at a time, each rebased
on the one before.
With this change, the changelog entry is a file of its own, and each of those list entries
lives in the file of the step, corpus or test it belongs to. The changelog and the
workflow's lists then no longer make two branches conflict, unless two pick the same file
name. Other files are still shared, and two changes can still conflict in them: "What stays
shared" below names them and says how to insert there.
What changes
Changelog entries are files of
wai/changes/wai/changes/<yyyy-mm-dd>-<slug>.md, holding the entry exactly as thechangelog would: a
###title, a blank line, then its text.wai/changes/README.mdstatesthe form.
scripts/changelog-assemble.py --writerenders the files into the head of## Unreleased(newest date first, then by file name within a date) and removes them. Thesame files always give the same bytes. Without
--writeit prints what it would write, and--checkchecks every file.scripts/check-changelog-fragment.pyis a new step of the repository checks. It fails apull request that changes anything under
wai/and adds or edits no entry file directlyin
wai/changes/. A release, which renders the entries and removes their files, passes.A change with nothing to record ends one of its commit messages with the trailer line
Changelog: none, exactly that line, in the message's trailer block. The check also fails, saying why, on an entry in a subdirectory, a malformed entry, or a range itcannot compare; it never passes unchecked. To make the comparison possible, the repository
checks job now checks out the whole history (
fetch-depth: 0).wai breakingreads the lines a change adds to entry files the same way it reads linesadded to the changelog, so a
**Breaking:**line in an entry acknowledges a break. The twopublic-text checks that exempt the changelog also exempt the entries waiting in
wai/changes/.The conformance workflow's lists and steps come from files of their own
Each step of the independent verifiers is a file,
verifiers/<name>.sh. The file holds thestep's shell body, unchanged, under a header of
# key: valuelines (step:,order:,features:,paths:,bins:,release-features:and the rest).Each cargo-class corpus is a file,
corpora/<name>.txt, that names its tool and directory.Each test of the fast integer kernels' steps tags itself in its first line:
// wai-conformance: int-kernels,int-kernels-amdorint-kernels-release.When the workflow runs,
scripts/wai-conformance-lists.pyderives these lists from thefiles:
One workflow step runs every verifier file in order, each in its own log group. As with a
failing step before, the first file that fails stops the job, and the error names that
file.
The workflow's trigger takes all of
wai/extensions/**, and drops the per-extension linesthat the step files now name. Its
relevantjob narrows that to the paths the workflowlists plus the paths the step files name. At run time the gate step reads the step
headers itself, through
scripts/pr-touches-paths.py --paths-from .github/wai-conformance/verifiers --wide 'wai/extensions/**'. The lists script'sselftestanddry-runcompute the same list by importing that script, and itscheckrequires the gate to read the same step paths the lists script's
pathscommand prints. A new step therefore bringsthe extension text it reads in its own file. For every file outside the two paths this
change adds to the gate (
.github/wai-conformance/**andscripts/wai-conformance-lists.py), the gate gives the same answer as before; for a fileunder those two, it now answers true.
scripts/check-tests-in-ci.pycounts a test as run when a step file names it or a steptakes a tag the test carries.
wai mcp's conformance tools read the verifier commands fromthe step files.
.github/wai-conformance/README.mdexplains the files.python3 scripts/wai-conformance-lists.py dry-runprints what the workflow runs,run --only <name>runs one step as CI does, and
checkchecks the files.Pull requests opened before this lands
Changelog. A pull request opened before the check reached main passes as it is,
whether it edits the head of
wai/CHANGELOG.mdor has no entry at all. A pull requestopened after the check reached main fails if it adds its entry to the head of
## Unreleased, and the message tells it to move the entry to a file ofwai/changes/.(A pull_request run reads its workflow from the pull request's head, so a branch cut
before the check reached main runs the check only once main is merged into it.) The check reads when the
pull request was opened from the event payload (
pull_request.created_at). It reads whenthe check reached main from the first-parent history of the pull request's base: the
committer time of the first commit there whose tree holds the check, which is this
change's merge commit, not the earlier commits of this branch. Until that merge the check
is on no base, and every pull request counts as opened before it landed.
The conformance workflow. A pull request that adds a step, a corpus or a kernel test to
the hand lists of
wai-conformance.ymlconflicts with this change in that file. On rebase,it takes the workflow as this change leaves it and moves its addition into a file:
verifiers/<name>.sh, with its features and paths in the headercorpora/selftestthen confirms that the hand lists' entries are all still there, anddry-runshows the new step.
What stays shared, and how to insert there
This change moves only the changelog entry and the conformance workflow's lists into files.
These are still edited by many changes, and two changes can still conflict in them:
wai/wai-rs/Cargo.toml's[features],[[bin]]and[[test]]tables (a new verifierstep usually adds a feature and a
[[test]]entry here)wai/wai-rs/src/lib.rs'smodlineswai/wai-rs/src/codecs/registry.rswai/.gitattributeswai/live-conformance/README.md, with the verifier commands under itwai-conformance.yml, when a step's# paths:names a file under none ofits paths (
checkfails such a step and names the path)These files are grouped by topic, not sorted. Insert a new entry beside the entry it builds
on, never at the end, and never re-sort:
Two changes that build on different entries then insert at different places and merge
cleanly. Two that build on the same entry insert at the same place and conflict; the one
that merges second resolves it by keeping both entries.
.gitattributesfile (
* -text), aswai/pin-conformance/andwai/live-conformance/scene/do, instead ofadding a line to
wai/.gitattributes.wai/registry/capabilities.json, the table inwai/REGISTRY.md,wai/vocab/v2.*) are sorted by the export. On a conflict in one of them, take either sideand run
wai registry exportagain.CLAUDE.mdandwai/CONTRIBUTING.mdstate these rules.How coverage is shown to be unchanged
selftest --exactagainst the hand lists..github/wai-conformance/baseline.jsonholds the lists
wai-conformance.ymlkept by hand on main ata223c597d.python3 scripts/wai-conformance-lists.py selftest --exactrequires every derived list to equal itshand list. It also requires each verifier step to have the working directory and body of
the hand list's step of the same name, in the same order, and names a step or a corpus the
tree adds as an addition. It passes on this branch. The only additions are the two gate
paths named under the dry-run diff below, which the baseline records as added. The
repository checks run
selfteston every pull request; it fails any change that drops anentry or a step of the hand lists.
The dry-run diff.
dry-runprints, in one stable form (flags and features sorted):every list, every verifier step, and the command lines of the integer kernels' steps, the
corpus step,
int-kernels-amdand the features-alone loop. The output for main and forthis branch differs in one line. That line is the paths the gate runs on (the
relevantjob's list), which gain
.github/wai-conformance/**andscripts/wai-conformance-lists.py, so a change to the files that now say what runs runsthe workflow's jobs, as a change to the workflow file does. The trigger itself
(
on: pull_request: paths:) gains those two andwai/extensions/**, and drops theper-extension lines the step files now name; the gate's list still holds those paths,
read from the step files. Every command line is the same. To reproduce:
diff <(python3 scripts/wai-conformance-lists.py dry-run --ref a223c597d) <(python3 scripts/wai-conformance-lists.py dry-run).The workflow steps. Each step of the two changed workflow files, named or not, was
compared with main's, by job and step name (a step with no name by its
idoruses).Every step has the same name and body except those this change adds or rewrites:
repo-checks.yml: the checkout step (no name) checks out the whole history(
fetch-depth: 0); and the new steps for the lists (their self-test andselftest)and for the changelog (its self-test,
changelog-assemble.py --checkand the pullrequest check).
wai-conformance.yml:relevant: its gate step (id: gate, no name) passes--paths-from .github/wai-conformance/verifiers --wide 'wai/extensions/**'toscripts/pr-touches-paths.py.cargo-classes: a step that makes sure python3 is present on the unix legs. The twointeger-kernel steps take their tests and features from the tags. The corpus step,
previously one step for the unix legs and one for Windows, is now one step for both
that reads
corpora/.int-kernels-amd: its kernel step's features come from theint-kernelstag, ascargo-classes' kernel steps' do (features int-kernels --extra-features i32_forms),and its tests from the
int-kernels-amdtag.independent-verifiers: a new step derives the feature lists, and the build stepbuilds the derived binaries and tests. One step that runs every file of
verifiers/replaces the step per module.
features-alone: the Rust step also makes sure python3 is present, and the loop readsthe derived lists.
Each removed per-module step is now a file of
verifiers/with the same body, whichselftest --exactchecks.Self-tests that fail closed.
scripts/wai-conformance-lists-selftest.shchecks that thederivation fails when coverage is lost:
fail
selftest --exactto nameeach as one addition, with no step of the hand list changed or moved
Its checks hold whatever else the tree holds, so a pull request that adds a step passes
them.
scripts/changelog-fragments-selftest.shbuilds scratch repositories and checkseach rule of the changelog check and the assembler, including the transition and shallow
clones. For the transition, main starts without the check, a branch adds it, and a pull
request opened after that branch's commit but before its merge, and one opened after the
merge, each edit the head of Unreleased: the first passes and the second fails.
What a contributor does now
wai/addswai/changes/<yyyy-mm-dd>-<slug>.mdwith its entry, andleaves the head of
wai/CHANGELOG.mdalone. If there is nothing to record, it ends a commitmessage with
Changelog: nonein the trailer block..github/wai-conformance/verifiers/<name>.sh: its body, withstep:,order:,features:andpaths:in the header. It adds no line towai-conformance.yml, unless itspaths:names a file under none of the trigger's paths.Any feature or
[[test]]entry it needs goes intowai/wai-rs/Cargo.toml, beside itssiblings.
.github/wai-conformance/corpora/. A newfast-kernel test carries
// wai-conformance: int-kernelsin its first line.python3 scripts/wai-conformance-lists.py dry-runshows what runsrun --only <name>runs one stepcheckchecks the step filespython3 scripts/changelog-assemble.py --checkchecks the entries🤖 Generated with Claude Code