release-checklist.md

PiShip maintainer release checklist

How the PiShip project qualifies and approves its own releases (such as the v0.9.1, v0.11.0, v0.12.0, and v0.13.0 GitHub pre-releases). This is the project's checklist, not a distribution owner's: a company that ships its own distribution follows the distribution owner's release checklist instead.

Nothing is published automatically: there is no npm publication or publish automation, and CI keeps artifacts only as workflow artifacts. A GitHub Release, such as the v0.13.0 pre-release, is created by hand from a qualified run's artifacts. The maintainer, Oliver, is the sole release approver. Before any publish step:

1. Dispatch Release qualification on the exact commit on main and confirm the run is green. It runs CI, CodeQL, Portable E2E, and Reference E2E on that commit, then Release candidate. Its release-candidate jobs must have passed on linux-x64, darwin-arm64, and win32-x64. It must show two builds on separate runners with equal payloads for each of acmecode, mypi, and devcode (the reproducibility-<distribution>-<target> reports), verify-release on a fresh job, and rejection of the tampered archive, the wrong digest, and the modified payload, release.json, SBOM, and checksums.txt, and an install with the shipped script on a fresh job, followed for mypi and devcode by the installed release's offline --smoke and doctor. Each verify job's summary (the Check the recorded release evidence step) must show registry signatures: passed for every distribution and target: a registry signatures: unavailable warning means npm or the Sigstore trust root could not be reached and the signatures were not checked, which is a reason to rerun the job, not to publish. The install jobs' summaries list the installed file count of each release. Attestations must verify with gh attestation verify --repo tc3oliver/piship --signer-workflow tc3oliver/piship/.github/workflows/release-candidate.yml --source-ref refs/heads/main. Its Portable E2E jobs must have passed on all three targets, including the lifecycle scenarios (tests/e2e/lifecycle-*.test.ts and tests/e2e/personal-lifecycle.test.ts), its Reference E2E job, the AcmeCode reference distribution against the enterprise reference stack on Ubuntu, must have passed, and its CodeQL job must be green.
2. For a milestone release, read the qualification matrix and its gaps against the run: every row it assigns to a workflow must have run in that workflow, and a gap that this release was meant to close must be closed or recorded in the release notes.
3. Confirm examples/demo-company/piship.lock was reviewed in the change that committed it, and that the Windows candidate is treated as the patched variant whose lock was generated in CI.
4. Confirm npm run check and npm run test:compatibility passed, and review piship diff between the previous and new release for its risk and required tests.
5. Review vulnerabilities.json and every release.vulnerabilities.allow exception and its expiry. The developer example audits its vendored package closure live; if a new high advisory stops either build, review the advisory before adding an expiring exception or updating the affected package.
6. Confirm the pinned release keys, and that the private key is held outside the repository and CI.
7. Record the archive SHA-256 values and attestation results.
8. Obtain the maintainer's explicit written approval for this specific commit and these artifacts. Without it, nothing is signed into a channel or published anywhere.
9. Only then sign the channel with a higher sequence and publish its directory. Rolling back a bad release means signing a channel that offers a newer, fixed version; clients refuse downgrades, and users can run rollback locally.