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 automatically:

• Determines version information from the tag.

• Builds F-Droid (APK) and Google (AAB, APK) artifacts. If artifacts for the same commit SHA have been built before, it will use the cached artifacts instead of rebuilding.

• Generates a changelog.

• Creates a draft GitHub Release and attaches the artifacts.

• Attests build provenance for the artifacts.

• Deploys to the Google Play Console using a smart "promote-or-upload" strategy based on the Git tag:

  • Internal Release (vX.X.X-internal.Y):

    • Always uploads the AAB to the internal track. The release is automatically finalized and rolled out to internal testers.

  • Promotions (-closed, -open, production):

    • The workflow first attempts to promote an existing build from the previous track. The promotion path is: internal -> NewAlpha (closed) -> beta (open) -> production.
    • Fallback Safety Net: If a promotion fails (e.g., the corresponding build doesn't exist on the source track), the workflow will not fail. Instead, it automatically falls back to uploading the newly built AAB directly to the target track as a draft.

This fallback mechanism makes the process resilient but adds a crucial manual checkpoint: any release created via fallback upload will be a draft and requires you to manually review and roll it out in the Google Play Console.

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 generally follow Semantic Versioning (e.g., vX.X.X).
   • Use the correct suffixes for the desired release phase:
     • 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

The recommended release process follows the promotion chain.

1. Start with an Internal Release: Create and push an -internal tag first.

   # 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. Promote to the Next Phase: Once the internal build is verified, create and push a tag for the next phase.

   # This will promote the v1.2.3 build from 'internal' to 'NewAlpha'
   git tag v1.2.3-closed.1
   git push origin v1.2.3-closed.1
   

Pushing each tag automatically triggers the release.yml GitHub Action.

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: The workflow attempts to promote the build from internal to the NewAlpha track.
• Manual Steps:
  1. GitHub: Find and publish the draft release.
  2. Google Play Console:
     • If promotion succeeded: The release will be live on the NewAlpha track. Verify its status.
     • If promotion failed (fallback): The AAB will be a draft on the NewAlpha track. You must manually review and submit it for your closed alpha testers.

Phase 3: Open Alpha / Beta Release

• Tag format: vX.X.X-open.Y
• Automated Action: The workflow attempts to promote the build from alpha to the beta track.
• Manual Steps:
  1. GitHub: Find and publish the draft pre-release.
  2. Google Play Console:
     • If promotion succeeded: The release will be live on the beta track. Verify its status.
     • If promotion failed (fallback): The AAB will be a draft on the beta track. You must manually review, add release notes, and submit it.

Phase 4: Production Release

• Tag format: vX.X.X
• Automated Action: The workflow attempts to promote the build from beta to the production track.
• Manual Steps:
  1. GitHub: Find the draft release. Crucially, uncheck "This is a pre-release" before publishing.
  2. Google Play Console:
     • If promotion succeeded: The release will be live on the production track.
     • If promotion failed (fallback): The AAB will be a draft on the production track. You must manually review, add release notes, and start a staged rollout.

Iterating on Pre-Releases

If bugs are found in a release:

1. Commit fixes to your development branch.
2. Create a new, incremented tag for the same release phase (e.g., if v1.2.3-open.1 had bugs, create v1.2.3-open.2).
3. Push the new tag. This will trigger a new upload to the internal track (if it's an internal tag) or a new promotion/fallback for other tracks.
4. Follow the manual post-workflow steps for that release phase again.