meshtastic-android/RELEASE_PROCESS.md

Release Process

This document outlines the process for creating and promoting releases for the Meshtastic Android application. The system is designed to be robust, auditable, and highly automated, using a combination of user-facing GitHub Actions "wizards" and a central, tag-triggered "engine".

Philosophy

• Git Tag Driven: The entire release lifecycle is initiated and controlled by pushing version tags to the repository.
• Automated Engine: A central workflow (release.yml) acts as the engine, listening for new version tags. It handles all the heavy lifting: building, versioning, uploading to Google Play, and managing GitHub Releases.
• User-Friendly Wizards: Manually creating tags is discouraged. Instead, two "wizard" workflows (create-internal-release.yml and promote-release.yml) provide a simple UI in the GitHub Actions tab to guide developers through creating and promoting releases safely.

Versioning Scheme

Releases follow a semantic versioning scheme, vX.Y.Z, with suffixes to denote the release channel and iteration.

• v2.8.0-internal.1: An internal build, iteration 1.
• v2.8.0-closed.1: A closed testing (Alpha) build.
• v2.8.0-open.1: An open testing (Beta) build.
• v2.8.0: The final production release.

---

The Release Lifecycle

Step 1: Creating a New Internal Build

This is the starting point for any new release, whether it's a brand-new version, a patch, or a hotfix.

1. Navigate to the Actions tab in the GitHub repository.
2. Select the "Create Internal Release Tag" workflow.
3. Click "Run workflow".
4. Fill in the base_version field with the version you want to create (e.g., 2.8.0).
5. Run the workflow.

What Happens Automatically:

• The wizard calculates the next iteration number (e.g., .1, .2, etc.) and pushes a new tag to the commit (e.g., v2.8.0-internal.1).
• The push triggers the release.yml engine, which builds the application, uploads it to the Google Play Internal track, and creates a corresponding draft pre-release on GitHub.

Step 2: Promoting an Existing Build

Once an internal build has been tested and is ready for a wider audience, you promote it.

1. Navigate to the Actions tab in the GitHub repository.
2. Select the "Promote Release" workflow.
3. Click "Run workflow".
4. Specify the target_stage (closed, open, or production). The default, auto, will automatically promote to the next logical stage.
5. Optionally, specify the base_version to promote. If left blank, the wizard will find the latest internal tag and use its base version.
6. Run the workflow.

What Happens Automatically:

• The wizard determines the correct commit from the latest internal tag for that base_version.
• It pushes a new promotion tag (e.g., v2.8.0-closed.1) to that commit.
• The push triggers the release.yml engine. It intelligently skips the build steps and proceeds to:
  • Promote the build on Google Play to the target track.
  • Update the existing draft GitHub Release, renaming it and marking it as a non-draft pre-release (or full release for production).

Special Case: Hotfixes / Superseding a Release

The system is designed to handle hotfixes gracefully. If v2.8.0-internal.1 has been created, but a critical bug is found, the process is simple:

1. Merge the fix into your main branch.
2. Go to the "Create Internal Release Tag" workflow again.
3. Enter the same base_version: 2.8.0.

What Happens Automatically:

• The wizard creates and pushes a new tag, v2.8.0-internal.2, to the new commit.
• The release.yml engine detects that an existing release for v2.8.0 points to an older commit.
• It correctly interprets this as a "superseding" event. It automatically deletes the old GitHub release and its base tag, effectively restarting the release process for v2.8.0 from the new, corrected commit. This prevents a broken or outdated build from ever being promoted.