This repository makes TRO declarations with
tro-utils, checks them using
tro-checks, and reports what it
found. The report for each target is listed in reports/README.md.
This repository does not define its own checks. It performs those defined by the
tro-checks module on candidates tro-utils makes from the arrangements and resources in this repository.
The image installs the release of tro-utils named by TRO_UTILS_VERSION in
Dockerfile, and the candidates change with that release only when it is changed
there. Moving that one line is the whole of a version bump: the candidates and the reports that go
with it are made by CI, in the image that line describes. See Updating
tro-utils.
| File | What it is |
|---|---|
arrangements/ |
The sets of files the candidates record as arrangements. |
resources/ |
The other files the candidates are made from. |
make-candidates |
Script that uses tro-utils to create the candidates from the arrangements and resources. |
candidates/ |
The candidates created by make-candidates and assessed by tro-checks. |
candidates/manifest.json |
Describes each candidate and lists the versions and tiers it targets. |
reports/ |
The reports of what the checks found. |
Dockerfile |
Installs a pinned commit of tro-checks and a particular release of tro-utils. |
.github/workflows/ |
Remake the candidates and the reports, check that the committed ones are the ones the image makes, publish the image, and watch for the checks changing. |
In the top-level directory of this repository, check the candidates and regenerate the reports:
make build-reports
This checks the candidates as they are, so a candidate edited by hand is checked as edited. To remake the candidates with tro-utils, discarding any such edits:
make build-candidates
These commands automatically download the Docker image they depend on if it isn't already on your machine. To later ensure you have the latest image, run make pull-image. After changing the Dockerfile locally, rebuild the image with make build-image.
Change the version in the one place it is named, and open a pull request with just that change:
ARG TRO_UTILS_VERSION=0.5.1
Everything else is done for you, in this order:
- Regenerate runs on the push, builds the image from the
Dockerfileon your branch, remakes the candidates and the reports in it, and commits them to your branch. Your pull request then holds the moved pin and the candidates and reports that go with it. Review what it committed: that diff is what the new release oftro-utilschanged. - Check candidates runs on the default branch and on pull requests from forks. It remakes the candidates and the reports the same way and fails where they differ from the committed ones, so a candidate or a report made anywhere but in this image cannot reach the default branch.
- Publish image runs when the merge reaches the default branch and pushes the image to
ghcr.io, tagged
latestandtro-utils-<version>, so the published image never lags the pin.
Nothing has to be remade by hand. Remaking locally is still worth doing to see the change before
pushing, but it has to happen in the image — make build-candidates runs tro-utils there, and
the candidates record the types libmagic names in that image and the timestamps the fixed clock
and zone in make-candidates give it. A candidate made against a different
tro-utils, a different libmagic or a different zone is not the one this repository checks, and
Check candidates rejects it.
REVIEWS.md is left alone by CI: it records who reviewed what rather than what the checks found,
and it names the commit it was written at, so it would differ on every run. Update it with make update-reviews.
The checks are not in this repository. The image imports tro-checks, and with it the versions of
the TRACE Specification the checks come from, with repro.require at the commit the Dockerfile
pins, the one place it is named:
ARG TRO_CHECKS_VERSION=<commit>
So the reports change only when that pin is moved, never because a cached layer happened to be
rebuilt. tro-checks' main moves often, though, and trace-main describes itself as changing
frequently.
Watch checks runs weekly, and when asked for. It builds the image with every layer afresh and
with tro-checks at the latest commit on its main in place of the pin, remakes the candidates and
the reports with the pinned tro-utils, and compares them with the committed ones. Where they
differ it files an issue — or comments on the open one, so a change nobody has got to yet does not
become an issue a week — and closes it once the difference is gone. Every report enumerates every
expectation by name, so a check that is added, removed, renamed or reworded shows up even where no
candidate's status changes. Where main has moved without changing anything, nothing is filed and
the pin stays where it is.
Nothing is committed by that run. Moving to the new checks is done like
updating tro-utils: open a pull request that moves the pin to the commit
the issue names, and Regenerate commits the candidates and the reports that go with it.
Who the issue is assigned to is ISSUE_ASSIGNEE in
watch-checks.yml.
Because that build is uncached it also picks up anything else that has moved: the image is built
from cirss/repro-parent:latest and installs its other packages unpinned. The issue says so where
the candidates differ as well, since the checks cannot change those.