Vendoring a new meta-schema version is a hand-run bash loop documented in docs/maintaining-meta-schemas.md: git cat-file blob per file, sha256sum, then hand-editing meta/index.json, then refreshing the fixture slice from the same tag.
Every trap in that procedure is one the documentation has to warn about, and each has been hit at least once:
- using
git show instead of git cat-file blob, which applies the checkout's end-of-line conversion and writes CRLF on Windows, changing every digest and failing only on Linux CI
- copying the wrong file set, since the set has grown twice (
oold-rules.json and oold-rules.schema.json in 1.0.0-rc.1, oold-meta-schema-base.json in 1.0.0-rc.2)
- updating the files but not
fixtures.tag, which once left the README claiming a release the slice had already moved past
A command would remove all three by construction rather than by warning.
Sketch
oold meta vendor <version> --from <path-to-oold-schema>:
- read the file set the release actually ships rather than a hardcoded list, and record it as that version's
files entry when it differs from the shared default
- write bytes verbatim, LF, no text conversion
- compute and record the sha256 of each file in
meta/index.json
- record tag, commit, commit date
- refresh
tests/data/oold/ from the same tag and set fixtures.tag
- refuse to overwrite an existing tracked version without an explicit flag
The existing tests (test_recorded_checksums_match_the_shipped_files, test_the_vendored_files_are_stored_with_unix_line_endings, test_the_fixture_slice_records_the_release_it_came_from) already assert the end state, so they become the acceptance criteria.
Raised from review of #114 (#114 (comment)).
Vendoring a new meta-schema version is a hand-run bash loop documented in
docs/maintaining-meta-schemas.md:git cat-file blobper file,sha256sum, then hand-editingmeta/index.json, then refreshing the fixture slice from the same tag.Every trap in that procedure is one the documentation has to warn about, and each has been hit at least once:
git showinstead ofgit cat-file blob, which applies the checkout's end-of-line conversion and writes CRLF on Windows, changing every digest and failing only on Linux CIoold-rules.jsonandoold-rules.schema.jsonin 1.0.0-rc.1,oold-meta-schema-base.jsonin 1.0.0-rc.2)fixtures.tag, which once left the README claiming a release the slice had already moved pastA command would remove all three by construction rather than by warning.
Sketch
oold meta vendor <version> --from <path-to-oold-schema>:filesentry when it differs from the shared defaultmeta/index.jsontests/data/oold/from the same tag and setfixtures.tagThe existing tests (
test_recorded_checksums_match_the_shipped_files,test_the_vendored_files_are_stored_with_unix_line_endings,test_the_fixture_slice_records_the_release_it_came_from) already assert the end state, so they become the acceptance criteria.Raised from review of #114 (#114 (comment)).