Android Release Notes Structure

Android Release Notes Structure

Creates directory structure for Play Store release notes with multi-locale support.

Prerequisites

• Android project

Inputs

Process

Step 1: Create Release Notes Directory Structure

# Create base directory (Fastlane metadata standard structure)
mkdir -p fastlane/metadata/android

# Ask user which locales to support
# Default: en-US
# Common: en-US, de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN, zh-TW

# Create changelogs directories for each locale
for locale in ${LOCALES}; do
  mkdir -p "fastlane/metadata/android/${locale}/changelogs"
done

Step 2: Create Template Release Note Files

For each locale, create fastlane/metadata/android/${LOCALE}/changelogs/default.txt:

cat > fastlane/metadata/android/en-US/changelogs/default.txt << 'EOF'
- New: [Feature name]
- Improved: [Enhancement description]
- Fixed: [Bug fix description]

Note: Keep under 500 characters. Focus on user-visible changes.
EOF

Step 3: Create Release Notes README

Create fastlane/metadata/android/README.md:

# Play Store Release Notes

This directory contains release notes for Google Play Store deployments using Fastlane.

## Structure

Each locale has its own changelogs directory with a `default.txt` file:

metadata/android/ ├── en-US/ │ └── changelogs/ │ └── default.txt ├── de-DE/ │ └── changelogs/ │ └── default.txt └── [other locales]/ └── changelogs/ └── default.txt

## Format Guidelines

**File Requirements:**
- File name: `default.txt`
- Encoding: UTF-8
- Maximum: 500 characters
- Plain text only (no markdown/HTML)

**Content Guidelines:**
- Focus on user-visible changes
- List most important first
- Use bullet points (-, •, or *)
- Be concise and clear
- Avoid technical jargon

## Example Release Notes

**Good:**

• New dark mode for easier nighttime reading
• Improved app startup speed by 50%
• Fixed crash when uploading large photos
• Updated design for better accessibility

**Avoid:**

• Refactored codebase architecture
• Updated dependencies to latest versions
• Various bug fixes and improvements
• Performance optimizations

## Supported Locales

Current locales: ${LOCALES}

To add a locale:
1. Create directory: `mkdir -p fastlane/metadata/android/LOCALE-CODE/changelogs`
2. Create file: `echo "Release notes" > fastlane/metadata/android/LOCALE-CODE/changelogs/default.txt`
3. Add translated release notes

## Common Locales

- en-US: English (United States)
- de-DE: German (Germany)
- es-ES: Spanish (Spain)
- fr-FR: French (France)
- it-IT: Italian (Italy)
- ja-JP: Japanese (Japan)
- ko-KR: Korean (Korea)
- pt-BR: Portuguese (Brazil)
- zh-CN: Chinese (Simplified)
- zh-TW: Chinese (Traditional)

## Automation with Fastlane

Release notes are automatically included by Fastlane during deployment:

```ruby
# In fastlane/Fastfile
lane :deploy_internal do
  # Fastlane automatically looks for changelogs in fastlane/metadata/android/{locale}/changelogs/
  upload_to_play_store(
    track: "internal",
    aab: "app/build/outputs/bundle/release/app-release.aab"
  )
end

Deployment command:

bundle exec fastlane deploy_internal

Updating Release Notes

Before each release:

1. Update default.txt files for all locales
2. Keep under 500 characters
3. Verify UTF-8 encoding
4. Test locally: wc -m fastlane/metadata/android/en-US/changelogs/default.txt

### Step 4: Create Tracks Documentation

Create `docs/PLAY_STORE_TRACKS.md`:

```markdown
# Google Play Store Release Tracks

Complete guide to Play Store release tracks and workflow.

## Track Types

### 1. Internal Testing
**Audience:** Up to 100 testers (team only)
**Review:** None (instant, < 1 minute)
**Best for:** Daily builds, CI/CD, quick iterations
**Access:** Email-based tester list

**Use when:**
- Testing new features rapidly
- Verifying CI/CD pipeline
- Quick bug fix validation

### 2. Closed Testing (Beta)
**Audience:** Unlimited invited testers
**Review:** Typically < 1 day
**Best for:** Beta program, QA team, stakeholders
**Access:** Email list or shareable link

**Use when:**
- Extended testing with real users
- Collecting feedback before public release
- Testing with diverse devices/OS versions

### 3. Open Testing
**Audience:** Anyone with the link
**Review:** 1-7 days (first submission)
**Best for:** Public beta, community testing
**Access:** Public Play Store link

**Use when:**
- Large-scale public beta
- Community-driven feature testing
- Stress testing infrastructure

### 4. Production
**Audience:** All users (or staged rollout)
**Review:** 1-7 days (first submission, then hours)
**Best for:** Official releases
**Rollout:** Staged (5% → 10% → 50% → 100%)

**Use when:**
- Ready for public release
- All testing complete
- Version approved for general availability

## Recommended Workflow

Development ↓ Push to main → Internal Testing (auto) ↓ Test & validate ↓ Deploy to Beta → Closed Testing (manual) ↓ Beta feedback (1-2 weeks) ↓ Tag release → Production (manual approval) ↓ Staged Rollout: Day 1: 5% → Monitor crash-free rate Day 2: 20% → Monitor ANR rate Day 3: 50% → Monitor user feedback Day 5: 100% → Complete rollout

## Promotion Between Tracks

**Internal → Closed:**
- Manual promotion in Play Console
- Or automated via GitHub Actions workflow

**Closed → Production:**
- Always requires manual approval
- Create GitHub release tag
- Triggers production deployment workflow

**Emergency Halt:**
If issues detected:
1. Run manage-rollout workflow with "halt" action
2. Fix issue
3. Deploy new version
4. Resume or start new rollout

## Best Practices

1. **Always test in Internal first**
   - Never skip to production
   - Catch obvious issues early

2. **Use Closed Testing for Beta**
   - Get real user feedback
   - Test on diverse devices
   - Minimum 1 week beta period

3. **Staged Production Rollouts**
   - Start at 5-10%
   - Monitor for 24-48 hours
   - Only increase if crash-free rate > 99%

4. **Monitor Key Metrics**
   - Crash-free rate (target: > 99.5%)
   - ANR rate (target: < 0.5%)
   - User ratings
   - Install/uninstall rates

5. **Have Rollback Plan**
   - Keep previous version available
   - Can halt rollout anytime
   - Can decrease rollout percentage

Verification

MANDATORY: Run these commands:

# Verify directory structure
test -d fastlane/metadata/android/en-US/changelogs && echo "✓ Release notes structure created"

# Verify default.txt files exist
ls fastlane/metadata/android/*/changelogs/default.txt && echo "✓ Release note files created"

# Verify documentation
test -f fastlane/metadata/android/README.md && echo "✓ README created"
test -f docs/PLAY_STORE_TRACKS.md && echo "✓ TRACKS guide created"

# Check character count (should be < 500)
wc -m fastlane/metadata/android/en-US/changelogs/default.txt

Expected output:

• ✓ Release notes structure created
• ✓ Release note files created
• ✓ README created
• ✓ TRACKS guide created
• Character count < 500

Outputs

Troubleshooting

"Character limit exceeded"

Cause: default.txt file > 500 characters Fix: Edit file to be more concise, focus on top 3-4 changes

"Encoding issues"

Cause: Non-UTF-8 encoding Fix: Save files as UTF-8: iconv -f ISO-8859-1 -t UTF-8 default.txt

Completion Criteria

• fastlane/metadata/android/ directory exists
• At least en-US/changelogs/default.txt file exists
• fastlane/metadata/android/README.md created
• docs/PLAY_STORE_TRACKS.md created
• All default.txt files are < 500 characters