Move the upstream pins

Move the upstream pins

Upstream watch runs scripts/check_upstream_release.py every week. The script’s docstring names two things that can go wrong with src/oscal/schema/metaschema/ with no change in this repository:¹

• NIST releases a newer OSCAL version, so the schema falls behind;
• the copied files drift from the tree they were taken from.

The script exits 1 on either, and the workflow then opens its issue or comments on the one already open.

The pins

The copy has no version in its path, so the script pins the release and the commit it was taken from. PINNED_TAG is v1.2.3, PINNED_COMMIT is e061961c7702afeabffdf5e59894d35e748dade1, and PINNED_PATH is src/metaschema. A comment asks that all three move together, with the schema header’s version, source and annotations, when the copy is replaced from a newer release. The umbrella schema’s header gives the release as version, the tag and the commit in its oscal_tag and oscal_commit annotations, and the tree in source. NOTICE records the same commit and release.²

tests/test_schema_rules.py fails when the header and the script disagree.³ test_header_pins_match_the_watch compares the annotations and source with the pins, and requires the tag to be v followed by version. test_modules_carry_the_pinned_version requires every module to carry the umbrella’s version, and each module’s source to name that release’s JSON schema under /ns/oscal/<version>/.

When NIST has released a newer OSCAL

The script’s report gives the steps:

1. Replace src/oscal/schema/metaschema/ with src/metaschema/ at the new tag, whose address the report gives. CONTRIBUTING.md asks that the folder be replaced whole from one release and never edited.⁴
2. Move the pins in scripts/check_upstream_release.py and the schema header.
3. Run just test, and update every enum that tests/test_schema_rules.py reports, so that each enum holds exactly the values of the lists it names in oscal_allowed_values.

When a copied file differs

The report names each copied file that differs from its counterpart in the pinned tree, or that has no counterpart there. CONTRIBUTING.md asks that the folder stay as upstream wrote it. When the GitHub API returns the pinned tree’s listing truncated, the report says so and asks for the copy to be compared by hand.

Footnotes

1. scripts/check_upstream_release.py, the docstring, the pins and the report lines check() writes ↩

2. NOTICE, the section OSCAL metaschema, by NIST ↩

3. tests/test_schema_rules.py, test_header_pins_match_the_watch, test_modules_carry_the_pinned_version and test_enums_render_the_pinned_metaschema ↩

4. CONTRIBUTING.md, the rule on src/oscal/schema/metaschema/ ↩