Move the upstream pins

Move the upstream pins

Upstream watch runs scripts/check_upstream_release.py every week. The script’s docstring names three things that can go wrong with no change in the repository:¹

• SchemaStore changes github-workflow.json or github-action.json, for example when GitHub adds a permission scope or a runtime, so the copy and the schema fall behind;
• the copied files drift from the commit they were taken from;
• GitHub releases a REST API version newer than the one the rules module follows.

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

The pins

• PINNED_COMMIT is the SchemaStore commit. The schema header gives it in source and in the schemastore_commit annotation, and NOTICE records it.
• PINNED_API_VERSION is the REST API version. The header gives it in the rest_api_version annotation.
• DOCS_READ is the date GitHub’s pages were read. The header gives it as version and in the docs_read annotation.

test_header_pins_match_the_watch in tests/test_schema_rules.py fails when the header and the script disagree on any of them.² So a new reading date moves DOCS_READ, version and docs_read together.

When SchemaStore has moved

1. Compare the pinned commit with SchemaStore’s default branch, at the address the report gives.
2. Replace both schema files from one SchemaStore commit, with SchemaStore’s LICENSE and NOTICE; never edit them in place.³
3. Move PINNED_COMMIT in the script, and the commit in the schema header’s source and annotations. Empty KNOWN_DIFFERENCES.
4. Update NOTICE.
5. Review the schema against the change, and run just test, whose tests compare the schema’s patterns and enums with the new copy.

When GitHub has a newer REST API version

1. Read that version’s section of GitHub’s page on breaking changes in the REST API, for changes to rulesets, rules or check runs.
2. Move PINNED_API_VERSION in the script and the rest_api_version annotation in the schema header.

GitHub’s documentation pages are versionless, so no script can watch them, and the report repeats the date they were read.

Footnotes

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

2. tests/test_schema_rules.py, test_header_pins_match_the_watch ↩

3. CONTRIBUTING.md, the rule on src/github_actions/schema/schemastore/ ↩