Release Notes¶
What changed in the surface you use, and what to do about it.
Binaries, checksums and the per-tag changelog are published as GitHub Releases
in
engineering-runtime-releases.
This page is the technical companion to those tags: which parts of the runtime
you interact with moved, and which of your files need attention.
Just looking for the download?
Releases on the Engineering Runtime site, or straight to the GitHub Releases page. Then follow Installation.
The binary is always the authority¶
Documentation examples on this site are written against v0.5.x unless a page says otherwise. When a page and your installed binary disagree, your binary wins — check it directly:
runtime <provider> --help is generated from the provider's real operation
surface, so it can never drift from what you have installed.
After every upgrade¶
Three checks, about ten seconds, that catch the overwhelming majority of post-upgrade surprises:
# 1. What does the new release ship by default?
TMP=$(mktemp -d)
ENGINEERING_RUNTIME_HOME=$TMP runtime bootstrap >/dev/null
diff ~/.engineering-runtime/policy-config.yaml $TMP/policy-config.yaml
diff ~/.engineering-runtime/config.yaml $TMP/config.yaml
# 2. Does the active configuration still resolve?
runtime config validate
# 3. Do all capabilities still validate against the new surface?
find "${RUNTIME_CAPABILITIES_DIR:-$HOME/.engineering-runtime/capabilities}" \
-name '*.md' -print0 |
while IFS= read -r -d '' f; do
runtime capability validate "$f" >/dev/null || echo "FAILED: $f"
done
Step 1 matters more than it looks — see the trap below.
What an upgrade touches¶
| Path | On upgrade |
|---|---|
specs/, commands/ |
Replaced to match the new binary; files it no longer ships are deleted |
version |
Updated |
config.yaml, policy-config.yaml, context.yaml |
Never touched |
| capabilities directory | Existing files never touched; newly shipped examples appear |
logs/, cache/ |
Untouched |
Full mechanics: Upgrading.
New defaults never reach an existing install
policy-config.yaml is yours, so a release that adds allowed_binaries
entries or new deny rules changes nothing on a machine that already has
the file. This has bitten real installs: a laptop sat at 6 allowed binaries
while the release shipped 21, and runtime command run helm was denied for
no apparent reason.
This is a deliberate trade — never clobbering your policy is worth more than
auto-delivering defaults — but it means the diff in step 1 above is how
you find out. Merge by hand; copying the new file wholesale discards your
own rules.
Where to look when something changed¶
| You noticed | Read |
|---|---|
| An operation no longer validates | runtime capability, then runtime <provider> --help |
| A command is suddenly denied | Policy and the trap above |
| A config key moved or was renamed | config.yaml, Environment Variables |
| A capability step key is now rejected | Capability Authoring |
| Something structural changed between versions | Migration Guides |
| A brand-new provider appeared | Providers |
Migration Guides documents breaking changes in detail —
the retired allowed_commands block, the move from a central command registry
to the Provider layer, and stricter capability parsing.
Downgrading¶
Supported and symmetric: specs/ and commands/ refresh back down to what
the older binary ships, because the refresh triggers on any version difference.
Your user-owned files are untouched in that direction too.
The one thing to re-check is capabilities — one written against an operation that exists only in the newer binary will fail validation after a downgrade. That is the intended behaviour, caught before execution rather than during it.