nsh-compat

The API Native Shell's releases froze, and the checks that hold later checkouts of NSH to it.

NSH apps are delivered to host apps as plugins and may never be built again, so every release of NSH runs every app built for an earlier compatible one. What a release shipped is recorded here, apart from NSH's code, so a change to NSH cannot rename an API and rewrite the record of it in the same pull request. The contract itself is NSH's docs/dev/compatibility.md.

releases/v<version>/    one per compatible release, written when it ships and never changed:
  runtime.txt           every module's exports (`nsh:rt` included) and the globals
  types/                the declarations apps build against
  tailwind.txt          every Tailwind class and what it sets
  apps/<app>/           the apps of NSH's tests/compat/ as that release built them, with their scripts
closed.txt              what was closed for security, the only removals, each with its reason
src/                    the checks

No release is recorded yet: nothing is frozen.

Running it

The crates depend on NSH's at ../nsh, the checkout under test. From an NSH checkout:

cargo xtask compat                      # clones this into target/nsh-compat/ and runs it against the checkout
cargo xtask compat record <version>     # records the checkout as a release here, to commit

With both repositories side by side:

(cd ../nsh && cargo build -p nsh-cli)
cp ../nsh/Cargo.lock . && cargo test --target-dir ../nsh/target

The tests:

• checkout_apps_run: NSH's tests/compat/ apps, built by the checkout's nsh build --release, do what their scripts say, and their covers claims hold;
• nothing_released_is_removed: everything each release here offered is still offered, the same or widened, less closed.txt;
• released_apps_run: every app each release built still starts and does what its script says.

NSH_COMPAT_APP=<name> runs one app, NSH_COMPAT_DUMP=1 prints the texts each step of a script adds and removes.

Changing it

A pull request here is reviewed by NSH's maintainers. A release record is added once, at the release, and never changed. A closure for security adds its entries to closed.txt with a reason, before the NSH change that removes them can pass. Changes to the checks keep every recorded release passing; CI runs them against NSH's main.