Release checklist
Publication gate for the three supported distribution shapes: editable install, Docker image, and PyInstaller bundle. Run this checklist before any release.
On this page
Pre-flight
- working tree is clean;
git statusshows what you expect -
pyproject.tomlversionis bumped -
CHANGELOG.mdhas a## [X.Y.Z] -- YYYY-MM-DDsection and nothing under## [Unreleased]; the tag gate refuses either omission -
README.mdis aligned with the behavior of the new release -
guides/CAPABILITIES.mdreflects any new or retired surface -
guides/ARCHITECTURE.mdreflects any new cross-module dependency -
site-docs/pages undersubsystems/,reference/, andhow-to/are updated where relevant -
Tools/HilBridge/RSPRO.asnis an up-to-date mirror of the operator's localdocs/RSPRO.asn(and still present as package-data inpyproject.toml) - operator-facing docs that reference
docs/describe it as an optional local developer tree (not as shipped content) - The local-only pre-release audit notes show no open action items that a release should ship with; anything explicitly deferred is listed in the "Deferred" blocks
-
pyflakes SCP03/ SCP11/ SCP80/ SIMCARD/ Tools/ main/ plugins/ yggdrasim_common/is clean modulo the two documented# noqa: F401probes and theSCP11/shared/SCP11/relaystar-import shims
Editable install
-
python -m pip install -e .succeeds in a clean venv -
every installed console script launches:
yggdrasim-scp03 --cmd "EXIT" yggdrasim-scp80 --cmd "exit" yggdrasim-scp11 --cmd "EXIT" yggdrasim-scp11-live --cmd "HELP; EXIT" yggdrasim-scp11-local-access --cmd "HELP; EXIT" yggdrasim-scp11-eim-local --cmd "HELP; EXIT" yggdrasim-profile-package --cmd "STATUS; EXIT" yggdrasim-profile-autoload --help yggdrasim-apdu-fuzzer --help yggdrasim-eum-diag --help yggdrasim-suci-tool --cmd "STATUS; EXIT" -
registry resolves:
python -c "from yggdrasim_common.registry import search; \ print(list(search('orchestrator'))[:5])"
Targeted test suite
Run narrowly-targeted pytest invocations that match the touched surfaces.
Do not mass-run. Redirect noisy runs to a log file and inspect with rg.
- each test file that exercises a changed area passes
- plugin runtime behavior is exercised through
tests/test_plugin_*.pywhere applicable - HIL-related tests pass in their emulated form
Docker
-
docker build -t yggdrasim:test .succeeds -
docker run --rm yggdrasim:test yggdrasim-profile-package --cmd "EXIT"exits cleanly - mounted-volume run persists state across invocations
PyInstaller bundle
-
pyinstaller --clean --noconfirm yggdrasim_main.specsucceeds -
dist/yggdrasimlaunches and writes the expected runtime tree - at least one card-facing surface works end-to-end against the bundled runtime material
- the runtime root resolution is correct for the target OS
Documentation site
-
python -m mkdocs build --strictsucceeds from the repo root - the mirrored
site-docs/sources/is regenerated viapython site-docs/_tools/mirror_source_docs.py - nav entries that reference new pages exist and resolve
- nav entries for removed pages are removed
Manual unsigned test draft
Use the Main Test Draft Release workflow only when a cross-platform test
bundle is needed before a production release. It is a manual
workflow_dispatch flow restricted to main; pull requests and ordinary
pushes never publish test assets.
- dispatch the workflow from
mainand confirm its recorded commit SHA is the exact revision you intend to test - confirm the workflow creates a new draft tagged
ci-main-<run-id>-<attempt>and records both the exact SHA and Actions run in its notes - confirm the draft is not the latest release and remains a draft; install
scripts must not consume
ci-main-*tags or the test-only asset names - treat every asset as an UNSIGNED TEST BUILD: Windows may display a Microsoft Defender SmartScreen warning, while the unsigned and unnotarized macOS build may be blocked by Gatekeeper
- confirm every primary asset has a
.sha256sidecar - for a successful run, confirm the final asset set also contains a
CycloneDX SBOM and a global
SHA256SUMS, and that the draft is marked COMPLETE - if any build or verification leg fails, confirm the draft is marked INCOMPLETE; do not mistake partial assets for a complete test set
- verify downloaded assets against their sidecars or
SHA256SUMSbefore testing them - remove a stale
ci-main-*draft yourself once diagnosis is done. The build workflow carries no delete path by design;CI Draft Cleanup(.github/workflows/ci-draft-cleanup.yml) reapsci-main-*andci-windows-main-*drafts older than seven days on a daily schedule, so anything worth keeping must be published or copied before then
This draft flow does not replace or weaken the production flow below. It never publishes a signed release, and it is not evidence that Windows signing, macOS signing/notarization, provenance, or production publication gates pass.
Windows-only test artifact
Use Windows Test Artifact when a single Windows x86_64 clean bundle is
enough. It is a manual, main-only flow and does not start the other platform
jobs.
- confirm the run attempts one Actions artifact with one-day retention; quota failure is visible but does not prevent the draft fallback
- confirm the unique
ci-windows-main-<run-id>-<attempt>draft remains a draft prerelease targeted at the dispatched SHA - confirm the draft has exactly one Windows ZIP and its
.sha256sidecar - confirm a COMPLETE draft was redownloaded, checksum-verified, extracted, and smoke-tested; never use an INCOMPLETE draft
- treat both executables as unsigned test builds that may trigger Microsoft Defender SmartScreen
Tagging and publishing
The publish flow is wired end-to-end in .github/workflows/build.yml. Pushing
an annotated v* tag triggers docs-strict + pytest-suite, the release
build matrix (Linux x86_64 / arm64 clean+full, macOS arm64 clean,
Windows x86_64 clean, Debian package) and the publish-release job. The
publish-release job:
- downloads every matrix artefact;
- renames each binary to the canonical name the install scripts consume
(
yggdrasim-{os}-{arch}-{flavor}[.exe], seescripts/install/_common.sh::yg_asset_nameandscripts/install/install-windows.ps1::Install-YgFromRelease); - generates a
SHA256SUMSmanifest; - guards the matrix against silent drift with an explicit "required asset"
list before calling
gh release create; - reads the annotated tag message from the tag object the policy job
verified, judges it with
scripts/release/release_notes.py check, callsgh release create <tag> --notes-file <notes> --verify-tag ..., and reads the page body back to compare it with the checked notes.
The annotated v* path remains the only production publication path. It uses
canonical installer-facing asset names and fails closed if any required
build, checksum, provenance, or publication gate does not pass. Windows
Authenticode signing and macOS signing plus notarization run when the
repository holds the WINDOWS_CODESIGN_* and MACOS_CODESIGN_* /
MACOS_NOTARY_* secrets. A repository without them publishes unsigned
binaries and the release notes gain a Code signing section that says so;
a partial set of secrets fails the build, because it is a misconfiguration
rather than a decision.
Before any platform build or signing step, CI also requires the tag to match
v<project.version>, verifies that it is annotated, confirms that its
exact commit is reachable from origin/main or from an origin/release/*
branch, and judges the tag message and CHANGELOG.md with the release-note
gate below.
Annotated-tag-message contract
The release page's body is the annotated tag message. Both
release-ref-policy (before any platform builds) and publish-release
(before gh release create) run scripts/release/release_notes.py check
on it and fail closed when:
- the message is empty, or is the tagged commit's message (a tag annotated
with
git log -1 --format=%Boutput reads as a commit on the page); - the first line is not
YggdraSIM vX.Y.Zfor the tag being published; - no line is a Markdown list item (
- ...), so the note names no change; - a line is a trailer (
...-by:or...-Session:); CHANGELOG.mdin the tagged tree has no## [X.Y.Z] -- YYYY-MM-DDsection, that section is empty, or## [Unreleased]still carries entries. The tagged tree ships whatever the changelog files under Unreleased, so at a production tag that section is empty.
publish-release reads the message from the tag object the policy job
verified (git/tags/<sha> on the API), never from the checkout:
actions/checkout re-points refs/tags/<tag> at the commit, which is how
gh release create --notes-from-tag published the v2.1.0 commit message
as its release notes. After creation the page body is read back and
compared with the checked notes. Tagging steps:
- move every
## [Unreleased]entry into the## [X.Y.Z] -- YYYY-MM-DDsection ofCHANGELOG.mdin the commit the tag will point at -
tag the release in git with an annotation that reads as a release note (covers headline behavioural changes, defaults, migration considerations):
git tag -a vX.Y.Z -m "$(cat <<'EOF' YggdraSIM vX.Y.Z First / next ... release. Notable changes: - ... - ... EOF )" -
run the gate on the local tag before the push; it reads the annotated tag, the tagged commit and the tagged tree's
CHANGELOG.mdfrom the checkout, and refuses a lightweight tag:python3 scripts/release/release_notes.py check --tag vX.Y.Z -
push the tag:
git push origin vX.Y.Z - confirm the tagged commit is already reachable from
origin/mainor from arelease/<major>.<minor>.xbranch; the release policy gate rejects production tags made from arbitrary commits or unmerged branches before any platform build starts - watch the workflow at
https://github.com/<repo>/actions. Thepublish-releasejob only runs onrefs/tags/v*; failures indocs-strict,pytest-suite, or any build leg short-circuit the release publish. -
confirm the GitHub Release page lists the seven asset names plus
SHA256SUMS:yggdrasim-linux-x86_64-clean yggdrasim-linux-x86_64-full yggdrasim-linux-arm64-clean yggdrasim-linux-arm64-full yggdrasim-macos-arm64-clean yggdrasim-windows-x86_64-clean.exe yggdrasim-clean_X.Y.Z_amd64.deb SHA256SUMS -
sanity-check that the install-script
releasemode resolves with the just-published tag, e.g.:YGGDRASIM_REPO=1oT/YggdraSIM \ scripts/install/install-linux.sh --version vX.Y.Z -
publish the Docker image (
.github/workflows/docker.yml) if that is part of the release.
Post-release
- smoke-test the published artifacts on a fresh host
- open issues for any deferred follow-up that surfaced during the checklist