# 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.