archy/docs/release-from-latest-main.md

Historical 2.0.3-alpha OTA and ISO procedure

This is a version-specific record, not the current release procedure. The commands below name old tags and artifacts. Use the current Release & Testing scope and exact release instructions before preparing or publishing a newer build.

Historical target: 2.0.3-alpha. The numeric patch had to exceed deployed 2.0.0-alpha+uat: the updater ignores suffixes when comparing versions. The existing v2.0.1-alpha and v2.0.2-alpha source tags are retained unchanged. Administrator-recovery and target-specific manifest corrections belong to this successor source boundary. See target-specific-release-manifests.md: guarded target test deployments precede final release publication.

1. Lead-owned review and freeze

Read unresolved entries in docs/post-1.8.22-regressions-20261001.md and the current operator acceptance ledger. Record every ngit proposal disposition and accepted merge commit. The original 20 proposals plus aggregate are applied at c32a925647eab63ba0f1cac7e6bd135b857d5b7b; subsequent dirty fixes need separate review and acceptance. Ref parity does not prove proposal disposition.

Prepare version declarations, lockfiles, generated catalogs and curated release notes before the source freeze. Review/merge once on ngit and mirror the exact accepted commits to Gitea. The lead creates the annotated release tag on that immutable versioned commit, under separate publication authority. Never retarget a published tag. Use a fresh clean checkout (detached at the tag is supported). Record HEAD and the annotated tag object, not just its peeled commit.

git status --short
git rev-parse HEAD refs/tags/v2.0.3-alpha refs/tags/v2.0.3-alpha^{commit}
python3 scripts/check-git-mirrors.py --local --ref refs/tags/v2.0.3-alpha
python3 scripts/check-git-mirrors.py --local --all
python3 scripts/release_payload.py source --version 2.0.3-alpha

Both reviewed main and annotated tag objects must match both mirrors before publication. Inventory unrelated advertised-history drift explicitly. No independent mirror merges, force pushes, or rewriting published history.

2. Prepare unsigned pending OTA artifacts

Set AAPT and APKSIGNER to the installed Android SDK tools if they are not on PATH. Packaging checks the APK's actual version against node metadata, v1/v2/v3 signatures (including the min-SDK-21 v1 path), and existing certificate pin. Qualified code59 is 0.5.39-debug, SHA256 abaf9fe0e25f3bcad166790a7ad24b69cb7f9849bc20dc2210c88eec62a1ccaa.

bash scripts/create-release.sh 2.0.3-alpha --dry-run
flock /tmp/opencode/release-heavy.lock bash scripts/create-release.sh 2.0.3-alpha

This runs the release harness, locked/offline native backend build, frontend, AIUI and radio builds, then stages artifacts under releases/v2.0.3-alpha/ and an unsigned manifest under releases/pending/v2.0.3-alpha/manifest.json. There are no test bypass flags. Backend tests use the isolated runner. All full UI/Rust/ISO builds and heavy fixtures take the shared lock for the entire run.

Preparation does not bump source versions, commit, create a tag, sign, or promote the public feed. It refuses existing candidate paths: retain failed attempts and investigate rather than overwrite possibly signed evidence. AIUI BUILD-INFO records the same clean commit as the manifest and annotated tag. Source mutation during builds is a failure, not permission to attribute dirty bytes to HEAD.

The frontend archive is flat. It carries exact Companion APK/JSON bytes and all runtime scripts/configs, including newly added D09/C01/network/typed helpers. archipelago-runtime/RELEASE-PAYLOAD.json declares the version, source commit and per-file SHA256. Archive verification rejects missing, stale, duplicate, linked, mis-permissioned or nested payloads. Payload delivery is not privileged installation/admission authority.

3. Operator signing, then ISO build

Only after artifact inputs exist, preparation prints the exact pending-manifest signing command. Run that command on the operator terminal. sign-manifest.sh requires an explicit pending path, validates staged bytes and frozen source, and uses the staged native verifier. Missing signers fail. Never provide mnemonic material to an agent, command line, report or file.

The ISO wrapper consumes the signed pending manifest; publishing the live feed first is neither needed nor permitted as a build prerequisite.

flock /tmp/opencode/release-heavy.lock bash scripts/build-iso-release.sh

The wrapper rechecks source/tag, manifest bytes/signature, release tests, catalog and Companion. It extracts the exact verified frontend archive for the builder, then compares its entire web payload against the ISO's extracted bytes. Only a newly created unambiguous ISO is accepted. Smoke and QEMU gates are mandatory. The successful build prints the exact ISO signing command once its input exists. The ISO signer refuses to overwrite an existing checksum document.

Kernel-lane checks must prove the selected ISO boot kernel and installed kernel are fixed Debian 6.12.113-1 or later. Installed and running evidence are distinct; an installed update does not fix a still-running vulnerable kernel. QEMU boot is not physical install/reboot acceptance.

4. Upload and verify; lead promotes the feed separately

After signing, artifact acceptance and explicit publication authority:

flock /tmp/opencode/release-heavy.lock bash scripts/publish-release-assets.sh 2.0.3-alpha gitea-vps2

The uploader checks clean tagged source, manifest source, exact mirrored refs, local hashes and cryptographic signatures. It uploads OTA and signed ISO assets, verifies public OTA downloads, release links, and full ISO/checksum/signature download hashes. It never merges branches, pushes tags, commits, or promotes the feed. Credentials stay in the credential helper. ISO signed JSON must describe the actual ISO, independently of the text checksum file.

The lead retains the upload receipts and required installed/physical/UAT acceptance, then prepares a canonical reviewed feed-promotion commit containing the exact verified signed manifest in both feed paths. Mirror that exact accepted commit, keeping the immutable build tag unchanged. Recheck both mirrors and public downloads after promotion. Do not rebuild/tag from the feed-promotion commit.

5. Acceptance remains separate

Source tests, synthetic artifacts and healthy services do not establish release acceptance. Retain independent evidence for immutable artifacts, normal native startup, guarded installed migration, OTA canary/reboot/rollback, clean ISO install, physical hardware and operator acceptance. Paid-file recovery must never repay; preserve wallets, persistent data and uninstall decisions. Record remaining deferrals honestly. No missing acceptance becomes a pass through this workflow.