trmnl-android/RELEASE_CHECKLIST.md

Release Checklist for TRMNL Android

This document outlines the process for creating new releases of the TRMNL Android app.

Version Management

The project uses GitHub Actions to manage version synchronization across different files:

• app/build.gradle.kts: Contains the app's version code and name
• fastlane/metadata/android/en-US/changelogs/: Contains version-specific changelog files

Creating a new release

1. Check current version information

# Show current version information and suggested next version
./scripts/show_version_info.sh

This will display:

• Current version code and name
• Existing changelog files
• Suggested next version

Example Run Output

🚀 Suggested next version:
  - Version Code: 22
  - Version Name: 2.0.4

To update version, run the GitHub Actions workflow 'Version Management' with:
  - Version name: 2.0.4
  - Version code: 22
  - Git tag: v2.0.4 (default)
  - Release notes: your comma-separated release notes

2. Run the Version Management workflow

• Go to GitHub Actions → Bump App Version workflow
• Click "Run workflow"
• Enter the required information:
  • Version name: Semantic version (e.g., 1.9.5)
  • Version code: Integer value, must increase with each release
  • Git tag (optional): Defaults to v + version name
  • Release notes: Comma-separated release notes
  • Create PR: Whether to create a pull request or commit directly

3. Wait for workflow completion

• The workflow will update all necessary files
• It will create or update the changelog
• It will commit changes

This automated process ensures consistency across all version-related files without manual edits.

4. Review PR and trigger CI

After the version management workflow has completed:

1. Review the PR (if you ran the workflow with direct commits):

2. Follow pre and post merge command guidelinse: Merge the PR. See PR description with guides.
3. Publish new release: Publish release for the new tag at https://github.com/usetrmnl/trmnl-android/releases

Create a GitHub release:

• Go to GitHub → Releases → Draft new release
• Select the tag created by the workflow
• Title: "Release v{VERSION_NAME}"
• Description: Copy content from the changelog file

This will trigger another workflow to automatically build the release APK and upload to the release. Here are some snapshot that shows the workflow being triggered and uploaded to the new published release

In case APK is not attached automatically, follow this 👇

**Download signed release build**: Use the workflow that automatically signs and builds release APK.

Example PR with instructions:

Workflow containing the built APK:

Unzipped artifact that is used for release:

Troubleshooting

If you encounter issues with the version management workflow:

1. Manual versioning:

   • Update app/build.gradle.kts with the new version code and name
   • Create a new changelog file in fastlane/metadata/android/en-US/changelogs/{VERSION_CODE}.txt
   • Commit and tag manually

2. Workflow permissions:

   • Ensure the GitHub Actions workflow has sufficient permissions to create commits and tags
   • Check the repository settings → Actions → General → Workflow permissions