Release Process

Quick Start

To release a new version:

npm run release

That's it! The script will:

1. Ask you for the new version number
2. Update all version files automatically
3. Create a git commit and tag
4. Push to GitHub
5. Trigger automated builds and deployments

What Gets Updated

When you run npm run release, these files are updated automatically:

File	What's Updated
app/pubspec.yaml	Flutter version + build number
app/lib/config/app_config.dart	Version constant
package.json	Root package version
backend/package.json	Backend version

Version Numbers

BookWish uses Semantic Versioning:

MAJOR.MINOR.PATCH

3.1.0
│ │ └── Patch: Bug fixes (3.1.0 → 3.1.1)
│ └──── Minor: New features (3.1.0 → 3.2.0)
└────── Major: Breaking changes (3.1.0 → 4.0.0)

The release script will suggest the next version based on these rules.

Build Numbers

Build numbers auto-increment with each release. They're required by the App Store and Play Store to distinguish builds.

• Version 3.1.0 with build 42 = 3.1.0+42
• Each release automatically increments: 42 → 43 → 44

What Happens After Release

When you push a version tag, GitHub Actions automatically:

iOS (TestFlight)

1. Builds the Flutter iOS app
2. Signs with your certificates
3. Uploads to TestFlight
4. Available to testers in ~15-30 minutes

Android (Play Store)

1. Builds the Flutter Android app bundle
2. Signs with your upload key
3. Uploads to Play Store Internal track
4. Available to testers in ~5-10 minutes

Web (Vercel)

1. Builds the Flutter web app
2. Deploys to Vercel
3. Live at bookwish.io in ~3-5 minutes

GitHub Release

1. Creates a release on GitHub
2. Generates changelog from commits
3. Tags the release

First-Time Setup

Before your first release, you need to configure secrets in GitHub:

Required Secrets

Go to: GitHub Repo → Settings → Secrets and variables → Actions

iOS Secrets

Secret	Description
APPLE_CERTIFICATE_BASE64	Your .p12 certificate, base64 encoded
APPLE_CERTIFICATE_PASSWORD	Password for the certificate
APPLE_PROVISIONING_PROFILE_BASE64	Your provisioning profile, base64 encoded
KEYCHAIN_PASSWORD	Any password (for CI keychain)
APP_STORE_CONNECT_API_KEY_ID	From App Store Connect API keys
APP_STORE_CONNECT_API_ISSUER_ID	From App Store Connect API keys
APP_STORE_CONNECT_API_KEY_BASE64	The .p8 key file, base64 encoded

Android Secrets

Secret	Description
ANDROID_KEYSTORE_BASE64	Your upload keystore, base64 encoded
ANDROID_KEYSTORE_PASSWORD	Keystore password
ANDROID_KEY_ALIAS	Key alias in keystore
ANDROID_KEY_PASSWORD	Key password
GOOGLE_PLAY_JSON_KEY_BASE64	Service account JSON, base64 encoded

Web Secrets (Flutter on Vercel)

Secret	Description
VERCEL_TOKEN	Vercel API token
VERCEL_ORG_ID	Your Vercel organization ID
VERCEL_PROJECT_ID	Your Vercel project ID

Vercel Environment Variables

Set these in Vercel Dashboard → Project → Settings → Environment Variables:

Variable	Description	Example
API_BASE_URL	Backend API URL	https://api.bookwish.io

How to Base64 Encode Files

# macOS/Linux
base64 -i your-file.p12 | pbcopy  # Copies to clipboard

# Or save to file
base64 -i your-file.p12 > encoded.txt

Manual Releases (Optional)

If you need to build locally without pushing:

iOS

cd app/ios
bundle install
bundle exec fastlane release

Android

cd app/android
bundle install
bundle exec fastlane release

Troubleshooting

"You have uncommitted changes"

Commit or stash your changes before releasing:

git add . && git commit -m "your message"
# or
git stash

"Tag already exists"

You can't release the same version twice. Choose a higher version number.

Build fails on GitHub Actions

1. Check the Actions tab for error logs
2. Verify all secrets are configured
3. Ensure certificates/keys haven't expired

TestFlight not showing new build

• Processing can take 15-30 minutes
• Check App Store Connect for processing status

Release Checklist

Before releasing:

• All tests pass locally
• Linting passes with no errors
• All PR reviews are complete
• CHANGELOG.md is updated
• No known critical bugs
• Database migrations are tested
• API changes are backward compatible (or version bumped)

After releasing:

• Monitor error tracking for new issues
• Check deployment logs for problems
• Verify app functionality on all platforms
• Monitor user feedback and app store reviews
• Update production documentation if needed

Version Planning

Patch Releases (x.x.X)

• Bug fixes
• Security patches
• Performance improvements
• No new features

Minor Releases (x.X.0)

• New features
• Non-breaking API changes
• UI improvements
• Backward compatible

Major Releases (X.0.0)

• Breaking changes
• Major new features
• Architecture changes
• Database schema breaking changes

Support

For issues with the release process, check:

1. GitHub Actions logs
2. App Store Connect (iOS)
3. Google Play Console (Android)
4. Vercel dashboard (Web)

References

• Semantic Versioning
• GitHub Actions Documentation
• Fastlane Documentation
• CI/CD Pipeline