release-and-store-shipping

Release and store shipping

CI proves the code; a release proves the artifact. Everything here is about the exact bundle a stranger installs — built with R8, obfuscation, tree-shaking, and release-mode asserts stripped, signed by a key you must never lose, declaring things about itself to a store that will pull the app if they are untrue. This skill starts where ci-pipeline-and-gates ends and where design-review-workflow signs off.

Building, signing, uploading, and tagging are side-effecting and irreversible in part (a published build number can never be reused; an iOS build can never be unshipped). Never run them because a task seemed to imply a release — run them only when the developer asks for a release by name. Reading and enforcing the config rules below is always in scope.

Run scripts/check-release-hygiene.sh before any release build (and in CI): it is the static half of this skill — tracked credentials, a malformed build number, debug signing, and debug affordances, none of which need a build to catch. Run scripts/check-ipa-slices.sh on the built IPA before spending an upload. Platform depth lives in references/android-play.md, references/ios-app-store.md, references/app-store-connect-submission.md, and references/privacy-permissions-and-claims.md.

Non-negotiable rules

1. pubspec.yaml's version: x.y.z+N is the only version source. x.y.z → versionName / CFBundleShortVersionString, N → versionCode / CFBundleVersion. Override per build only with --build-name / --build-number; never hardcode a version in build.gradle or Info.plist. WHY: two sources silently diverge and the crash report then names a version that never shipped.
2. The build number only ever goes up, and a published one is burned forever. Play rejects a reused or lower versionCode; App Store Connect rejects a reused CFBundleVersion for the same short version. A failed upload still burns the number — bump, don't retry.
3. No signing material in the repository, ever. Keystore/.jks/.p12, the App Store Connect API key (.p8), the Play service-account JSON, and android/key.properties are gitignored and injected from a secret store. WHY: a key in git history is compromised permanently, and rotating an app signing key is a store-side process you do not want to discover during a release.
4. Enroll in Play App Signing and keep the upload key separate. With Play App Signing, a lost upload key is recoverable via support; a lost app signing key for an unenrolled app means the listing can never be updated again — a dead app.
5. Obfuscate and split debug info, then archive the symbols with the artifact. --obfuscate --split-debug-info=<dir> is mandatory for every uploaded build, and <dir> must be versioned per build (symbols/<x.y.z>+<N>/) and stored off-machine. WHY: symbol files are the only way to read that release's stack traces; regenerating them later produces different symbols and decodes nothing.
6. Verify the release artifact itself, on real hardware. Install the exact .aab (via Play internal app sharing / bundletool) or the exact TestFlight build — never a debug or profile build, never "it worked in the emulator." WHY: R8, resource shrinking, and obfuscation only run in release, so reflective plugins, missing ProGuard rules, and stripped asserts fail first in the artifact you ship.
7. Assert the permission set whole, from the MERGED manifest. Transitive plugins inject permissions you never wrote. Read the merged output (not your source manifest), strip what you do not need with tools:node="remove", and keep a committed expected-permission list that a gate diffs against. On iOS every NS*UsageDescription present must be honest and every one you need must exist — a missing usage string is an App Review rejection, an unused one is a claim you cannot defend. See references/privacy-permissions-and-claims.md.
8. Every store declaration must be provable in the repo. Play Data Safety, App Store privacy nutrition labels, and PrivacyInfo.xcprivacy (required-reason APIs
   • third-party SDK privacy manifests) describe what the code does. Add a crash reporter, an ads SDK, or an analytics package and the declaration changes in the same PR. WHY: a false declaration is a takedown, not a warning.
9. No absolute privacy claims. Ban "nothing ever leaves your device" and "completely private" as listing/onboarding copy. State the mechanism instead — what is stored, where, what leaves, and when. WHY: one crash upload, one share-sheet export, or one map tile makes the absolute sentence a lie.
10. Debug affordances must be unreachable in release. Dev menus, fixture seeding, eraseDatabaseOnSchemaChange, log-everything sinks, and staging endpoints are compiled out or behind a flavor that is not the store flavor — proved by a grep gate, not by memory. WHY: shipped, they wipe or leak real user data.
11. Size and cold start are measured on the release build and recorded per release. --analyze-size for bytes, --trace-startup in profile for the first frame, on a real low-end target device. A regression past the recorded budget is a release blocker, not a note.
12. Roll out in stages with a written halt criterion. internal → closed → production at a staged percentage, with the crash-free-sessions threshold that triggers a halt decided before the rollout starts. WHY: Play rollouts can be halted; an App Store release can only be superseded by another build.
13. One tagged commit ships. Tag the exact commit, attach release notes, and keep the artifact + symbol archive with the tag. The dated design-review sign-off (design-review-workflow) is a precondition, not part of this pass.
14. Store-side gates are account-holder-only, and store-side state is never assumed. Creating the app record, the privacy questionnaire, and the Paid Applications Agreement have no API and block on a human — raise them on day one. An inactive Paid Applications Agreement makes StoreKit return zero products, which presents as a broken purchase button, not as a missing agreement. Everything that is API-settable (price, territory availability, in-app purchase state, screenshots, metadata) is read back from the store before submission — a green upload log is not server state, and a committed screenshot folder is not an uploaded screenshot set. WHY: every one of these blocks submission with a message that names a symptom rather than the setting.
15. A first release submits the app version AND its first in-app purchase together. Apple requires the first purchase of each type to ride an app-version submission; ship the version alone and App Review closes the submission without reviewing the app (Guideline 2.1(b)), and the remedy costs a new binary plus a full review cycle. Verify with one request before submitting — GET /v1/reviewSubmissions/{id}/items must return 2 items, not 1. WHY: a configured purchase reports a submittable state that reads, to every tool and every human, exactly like a submitted one. See references/app-store-connect-submission.md.