org.parres.whitenoise/RELEASE.md

Release Automation

This repo uses Fastlane as a thin wrapper around the existing Flutter, Rust, and shell build scripts.

Current Scope

The first release automation layer is build-only:

• validates that pubspec.yaml has a release version with a build number
• optionally validates that a git tag matches the pubspec version
• builds staging Android split APKs and AAB for org.parres.whitenoise.staging
• builds production Android split APKs and AAB for org.parres.whitenoise
• builds staging iOS IPA for dev.ipf.whitenoise.staging
• builds production iOS IPA for org.parres.whitenoise
• stages artifacts under build/releases/v<version>+<build>/<flavor>/

Staging and production are separate apps on both Android and iOS. Current iOS publishing target for both apps is App Store Connect/TestFlight. Store release submission, GitHub Releases, Zap Store, and Play Store upload lanes will be added after signing and account setup are stable.

Current app IDs:

• Production Android: org.parres.whitenoise
• Production iOS: org.parres.whitenoise
• Staging Android: org.parres.whitenoise.staging
• Staging iOS: dev.ipf.whitenoise.staging

If production moves under the IPF namespace later, the expected target would be dev.ipf.whitenoise for production and dev.ipf.whitenoise.staging for staging on both platforms.

Setup

Install the Fastlane bundle:

bundle install

Manual Release Runbook

The current release flow is local build automation plus manual uploads.

Set the release version:

export RELEASE_VERSION=2026.4.28
export RELEASE_BUILD=23
export RELEASE_TAG=v2026.4.28+23

1. Update pubspec.yaml.

   version: 2026.4.28+23
   

2. Update CHANGELOG.md.

   Move the current Unreleased content into a dated release section and add a fresh Unreleased section above it:

   ## Unreleased
   
   ### Added
   
   ### Changed
   
   ### Deprecated
   
   ### Removed
   
   ### Fixed
   
   ### Security
   
   ## [2026.4.28] - 2026-04-28
   

3. Run the pre-release checks.

   just precommit-check
   just test-release-scripts
   just release-doctor
   

4. Commit the release prep.

   git add pubspec.yaml CHANGELOG.md RELEASE.md
   git commit -m "chore: prepare ${RELEASE_TAG}"
   

5. Create the annotated tag on the release commit.

   git tag -a "${RELEASE_TAG}" -m "Release ${RELEASE_TAG}"
   

6. Validate the tag guard.

   just release-doctor "${RELEASE_TAG}"
   

   This fails unless pubspec.yaml matches the tag, the tag exists, and the tag points at the current HEAD.

7. Build staging and production artifacts.

   just release-build-all "${RELEASE_TAG}"
   

   Release artifacts are staged under:

   build/releases/v2026.4.28+23/staging/android/
   build/releases/v2026.4.28+23/staging/ios/
   build/releases/v2026.4.28+23/production/android/
   build/releases/v2026.4.28+23/production/ios/
   

8. Upload artifacts manually.

   Current upload targets:

   • GitHub Release: production APKs
   • Zap Store: production arm64 APK selected by zapstore.yaml
   • App Store Connect/TestFlight: staging IPA and production IPA
   • Play Store: production AAB after Play setup is complete
   • Play Store staging app: staging AAB after Play setup is complete

9. Push the release commit and tag after the build is verified.

   git push origin HEAD
   git push origin "${RELEASE_TAG}"
   

Commands

Validate the current release version:

just release-doctor

Validate the current release version against a tag that exists on HEAD:

just release-doctor v2026.3.23+22

When a tag is passed, the validator requires all of these to be true:

• pubspec.yaml contains version: 2026.3.23+22
• the tag name is v2026.3.23+22
• the tag exists in git
• the tag points at the current HEAD

Build the staging app release artifacts:

just release-build-staging

Build the production app release artifacts:

just release-build-production

Build both staging and production app release artifacts:

just release-build-all v2026.3.23+22

Build only staging Android artifacts:

just release-build-android-staging

Build only production Android artifacts:

just release-build-android-production

Build only staging iOS artifacts:

just release-build-ios-staging

Build only production iOS artifacts:

just release-build-ios-production

Secrets

Do not commit store credentials, App Store Connect API keys, provisioning files, or Android keystores. Fastlane local credential files such as .p8 and .json files under fastlane/ are ignored by git.