puter/RELEASE_CHECKLIST.md

puter release checklist

This checklist is the authoritative handoff for producing a public puter release. Run it from the repository root on a macOS runner.

Local quality gates

• swift test --parallel passes, including native full/lightweight sampler budgets, process sort semantics, memory pressure, storage, power parsing, helper input validation, security inspection, recording, alerts, and diagnostic serialization.
• ./scripts/build-app.sh produces a Hardened Runtime app with the live Icon Composer asset, Sparkle framework, command-limited helper, launch-daemon property list, and SMC backend/license when available.
• ./scripts/build-dmg.sh produces a drag-to-install DMG.
• ./scripts/validate-package.sh validates signatures, nested code, runtime search paths, Sparkle linkage, bundle metadata, Icon Composer configuration, helper payload, SMC payload/license, DMG checksum, mounted app, and Applications shortcut.
• Packaged-app accessibility smoke tests cover sidebar hide/recovery, the descending/ascending/categorized sort cycle, process rows, and live Hardware values.
• Current sampler benchmark: full process telemetry 0.0529 seconds/iteration; lightweight system telemetry 0.0076 seconds/iteration.
• Current 20-second packaged Hardware-page benchmark: 0.83% average CPU, 9.7% one-second peak while hardware work completed.

Benchmark numbers are evidence from the development Mac, not universal product guarantees. CI enforces the portable per-iteration budget rather than a machine-specific CPU percentage.

Required protected release inputs

• DEVELOPER_ID_P12_BASE64: Developer ID Application certificate and private key in PKCS#12 form.
• DEVELOPER_ID_P12_PASSWORD: PKCS#12 password.
• DEVELOPER_ID_IDENTITY: exact Developer ID Application: … (TEAMID) identity.
• APPLE_NOTARY_KEY_BASE64: App Store Connect API private key.
• APPLE_NOTARY_KEY_ID and APPLE_NOTARY_ISSUER_ID.
• SPARKLE_FEED_URL, SPARKLE_PUBLIC_KEY, SPARKLE_PRIVATE_KEY, and SPARKLE_DOWNLOAD_PREFIX.
• RELEASE_TOKEN: token allowed to create a release and upload assets to this Gitea repository.
• Stats-derived smc executable through PUTER_SMC_SOURCE, or Stats installed at /Applications/Stats.app on the runner.

Never commit certificates, API keys, Sparkle private keys, or release tokens.

Signed release procedure

1. Confirm the working tree and intended tag are clean and reviewed.

2. Confirm security find-identity -v -p codesigning lists the Developer ID Application identity.

3. Run the local gates above.

4. Push a semantic version tag such as v1.0.0.

5. The Signed release workflow must:

   • import the certificate into an ephemeral keychain;
   • build with Hardened Runtime, library validation, update feed, and EdDSA public key;
   • validate the signed app and DMG before submission;
   • submit to Apple, staple and validate both app and DMG;
   • validate the notarized package again;
   • generate the EdDSA-signed appcast;
   • publish the notarized DMG, stapled app ZIP, appcast, and SHA256SUMS.

6. Download the published assets on a separate Mac and run:

   hdiutil verify puter-macOS.dmg
   spctl --assess --type open --context context:primary-signature -v puter-macOS.dmg
   xcrun stapler validate puter-macOS.dmg
   

7. Install into /Applications, launch it, approve the helper only when testing fan control, and verify monitoring works without helper approval.

8. Exercise Check for Updates against the published appcast from the previous release before announcing the new release.

Release acceptance

A release is complete only when Apple notarization is accepted, stapler and Gatekeeper validation pass, the Gitea assets are downloadable with matching SHA-256 values, Sparkle verifies the appcast, and the installed app passes the packaged smoke tests. An ad-hoc or Apple Development build is not a public release.