ScottW514
e36a322ec5
Every fact in the two documents is now on the documentation site, which is the single source of truth. This repository carries no project documentation any more: it is the build and release base plus the acceptance tool, the bench tools and the fixture firmware. BRINGUP.md was the runbook, the hardware facts bank and the open-work list. CAMPAIGN-LOG.md was the dated record of how each result was obtained. What replaces them: the site for present state, and the commit message for the record of what a change did and how it was proven, so the change and its record stay together. Local open work is the developer's own file at the tree root and is not tracked here. README.md becomes an index card: what this is, build, test, and where the documentation is. The release pipeline tags the documentation. Firmware on a machine needs the documentation that agrees with it, so release.sh now tags the forgefirm-docs checkout with the same v<version> as the release, and prints the command that pushes the tag with the release. The checkout must exist and be clean, which is a new gate before the signature. FORGEFIRM_DOCS_DIR names the checkout (default: the sibling one) and FORGEFIRM_DOCS_SKIP releases without a tag, loudly, and is never the default. The tag is made at staging and pushed with the release, never before: a documentation tag for a release that never shipped is worse than no tag. No catalog consequence. release.sh is host-side and is in no image. The commission.py change is one sentence of a test description, not behavior. accel_crash_probe.py and the kas header lose pointers to the retired files. Checks: bash -n and sh -n on release.sh, and the tracked trees carry no reference to either retired file.
forgetest - the ForgeFIRM release acceptance tool
The daemon behind http://<machine>:8090/ on the dev image: runs the
acceptance catalog against the machine, keeps the append-only result log,
decides which results still apply to the image that is running, exports
the release artifact scripts/release.sh gates on, and serves the bench
diagnostics page. The contract - catalog, campaigns, fingerprints,
inheritance, the gate, the coverage rule - is
the Acceptance page of the documentation site.
Run the host tests
cd forgetest
python3 -m unittest discover -s tests -v
Run the daemon on a workstation (against a mock or a manifest file)
FORGETEST_DATA=/tmp/ft FORGETEST_MANIFEST=../tree-manifest.json \
FORGECTRL_URL=http://<machine> python3 -m forgetest --port 8090
scripts/manifest-from-tree.py produces tree-manifest.json from the recipe
pins; the coverage lint is python3 -m forgetest.coverage --manifest ....
Environment
| Variable | Default | Purpose |
|---|---|---|
FORGETEST_DATA |
/data/forgetest |
results.jsonl, bench.jsonl, token, export/ |
FORGETEST_MANIFEST |
/etc/forgefirm-manifest.json |
the image manifest |
FORGETEST_PORT, FORGETEST_HOST |
8090, 0.0.0.0 | listener |
FORGETEST_BENCH_DIR |
/usr/share/forgetest/bench |
the installed bench scripts |
FORGETEST_BENCH_DATA |
<FORGETEST_DATA>/bench |
passed to bench tools: where they keep their data files (with GF_HOST=127.0.0.1 and the panel token in GF_TOKEN) |
FORGETEST_MARKER |
/run/forgetest.active |
takeover marker |
FORGECTRL_URL, FORGECTRL_TOKEN_FILE |
http://127.0.0.1, /data/forgefirm/panel.token |
forgectrl client (HTTP; the token authorizes writes from the board) |
FORGECTRL_TLS_URL |
https://127.0.0.1 |
forgectrl over HTTPS (self-signed, unverified), for the login test |
GF_SYSFS_ROOT |
/sys/glowforge/ |
kernel module sysfs |
GRBL_HOST, GRBL_PORT |
127.0.0.1, 23 | Grbl TCP |
Adding a test
Register it in the subsystem module under forgetest/suite/ with
@test(...): id subsystem.name, kind, hardware, mode (the controller
mode the test needs; the runner switches to it first), covers,
requires, always, steps. The body gets a Context (log, check, fail,
prompt, confirm, instruct, sleep, evidence, forgectrl, sysfs,
grbl, takeover). Return normally for PASS, raise runner.Failed for
FAIL. Then run the unit tests and the coverage lint.