Meshtastic-Android/RELEASE_PROCESS.md

Meshtastic-Android Release Process

This document outlines the steps for releasing a new version of the Meshtastic-Android application. Adhering to this process ensures consistency and helps manage the release lifecycle, leveraging automation via the release.yml GitHub Action.

Note on Automation: The release.yml GitHub Action is primarily triggered by pushing a Git tag matching the pattern v* (e.g., v1.2.3, v1.2.3-open.1). It can also be manually triggered via workflow_dispatch from the GitHub Actions UI.

The workflow uses a simple and robust "upload-only" model. It automatically:

• Determines a versionName from the Git tag.
• Generates a unique, always-increasing versionCode based on the number of minutes since the Unix epoch. This prevents versionCode conflicts and will not overflow until the year 6052.
• Builds fresh F-Droid (APK) and Google (AAB, APK) artifacts for every run.
• Creates a draft GitHub Release and attaches the artifacts.
• Attests build provenance for the artifacts.
• Uploads the newly built AAB directly to the appropriate track in the Google Play Console based on the tag.

There is no promotion of builds between tracks; every release is a new, independent upload. Finalizing and publishing the GitHub Release and the Google Play Store submission remain manual steps.

Prerequisites

Before initiating the release process, ensure the following are completed:

1. Main Branch Stability: The main branch (or your chosen release branch) must be stable, with all features and bug fixes intended for the release merged and thoroughly tested.
2. Automated Testing: All automated tests must be passing.
3. Versioning and Tagging Strategy:
   • Tags must start with v and follow Semantic Versioning (e.g., vX.X.X).
   • Use the correct suffixes for the desired release track:
     • Internal/QA: vX.X.X-internal.Y
     • Closed Alpha: vX.X.X-closed.Y
     • Open Alpha/Beta: vX.X.X-open.Y
     • Production: vX.X.X (no suffix)
   • Recommendation: Before tagging, update VERSION_NAME_BASE in buildSrc/src/main/kotlin/Configs.kt to match the X.X.X part of your tag. This ensures consistency for local development builds.

Core Release Workflow: Triggering via Tag Push

1. Create and push a tag for the desired release track.

   # This build will be uploaded and rolled out on the 'internal' track
   git tag v1.2.3-internal.1
   git push origin v1.2.3-internal.1
   

2. Wait for the workflow to complete.
3. Verify the build in the Google Play Console and with testers.
4. When ready to advance to the next track, create and push a new tag.

   # This will create and upload a NEW build to the 'NewAlpha' (closed alpha) track
   git tag v1.2.3-closed.1
   git push origin v1.2.3-closed.1
   

Iterating on a Bad Build

If you discover a critical bug in a build, the process is simple:

1. Fix the Code: Merge the necessary bug fixes into your main branch.
2. Create a New Iteration Tag: Create a new tag for the same release phase, simply incrementing the final number.

   # If v1.2.3-internal.1 was bad, the new build is v1.2.3-internal.2
   git tag v1.2.3-internal.2
   git push origin v1.2.3-internal.2
   

3. A New Build is Uploaded: The workflow will run, generate a new epoch-minute-based versionCode, and upload a fresh build to the internal track. There is no risk of a versionCode collision.

Managing Different Release Phases (Manual Steps Post-Workflow)

After the release.yml workflow completes, manual actions are needed on GitHub and in the Google Play Console.

Phase 1: Internal / QA Release

• Tag format: vX.X.X-internal.Y
• Automated Action: The AAB is uploaded to the internal track and rolled out automatically.
• Manual Steps:
  1. GitHub: Find the draft release, verify artifacts, and publish it if desired.
  2. Google Play Console: Verify the release has been successfully rolled out to internal testers.

Phase 2: Closed Alpha Release

• Tag format: vX.X.X-closed.Y
• Automated Action: A new AAB is built and uploaded as a draft to the NewAlpha track.
• Manual Steps:
  1. GitHub: Find and publish the draft release.
  2. Google Play Console: Manually review the draft release and submit it for your closed alpha testers.

Phase 3: Open Alpha / Beta Release

• Tag format: vX.X.X-open.Y
• Automated Action: A new AAB is built and uploaded as a draft to the beta track.
• Manual Steps:
  1. GitHub: Find and publish the draft pre-release.
  2. Google Play Console: Manually review the draft, add release notes, and submit it.

Phase 4: Production Release

• Tag format: vX.X.X
• Automated Action: A new AAB is built and uploaded to the production track. By default, it is configured for a 10% staged rollout.
• Manual Steps:
  1. GitHub: Find the draft release. Crucially, uncheck "This is a pre-release" before publishing.
  2. Google Play Console: Manually review the release, add release notes, and start the staged rollout.