|
| 1 | +# Alpha Release Process |
| 2 | + |
| 3 | +This document describes how to create alpha releases for QA testing and early customer access. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The Rocket.Chat Desktop app supports three release channels: |
| 8 | +- **Stable** (`latest`) - Production releases for all users |
| 9 | +- **Beta** - Pre-release testing with broader audience |
| 10 | +- **Alpha** - Early testing for QA and select customers |
| 11 | + |
| 12 | +## How Channels Work |
| 13 | + |
| 14 | +| Channel | Version Format | Who Gets It | Update File | |
| 15 | +|---------|---------------|-------------|-------------| |
| 16 | +| Stable | `4.12.0` | All users (default) | `latest.yml` | |
| 17 | +| Beta | `4.12.0-beta.1` | Beta opt-in users | `beta.yml` | |
| 18 | +| Alpha | `4.12.0-alpha.1` | Alpha opt-in users | `alpha.yml` | |
| 19 | + |
| 20 | +**Channel hierarchy**: Alpha users receive alpha, beta, AND stable updates. Beta users receive beta AND stable. Stable users only receive stable. |
| 21 | + |
| 22 | +## Creating an Alpha Release |
| 23 | + |
| 24 | +### 1. Create Release Branch |
| 25 | + |
| 26 | +```bash |
| 27 | +git checkout master |
| 28 | +git pull |
| 29 | +git checkout -b release/4.12.0-alpha.1 |
| 30 | +``` |
| 31 | + |
| 32 | +### 2. Update Version |
| 33 | + |
| 34 | +Edit `package.json`: |
| 35 | +```json |
| 36 | +{ |
| 37 | + "version": "4.12.0-alpha.1" |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +### 3. Commit and Push |
| 42 | + |
| 43 | +```bash |
| 44 | +git add package.json |
| 45 | +git commit -m "chore: bump version to 4.12.0-alpha.1" |
| 46 | +git push origin release/4.12.0-alpha.1 |
| 47 | +``` |
| 48 | + |
| 49 | +### 4. Create and Push Tag |
| 50 | + |
| 51 | +```bash |
| 52 | +git tag 4.12.0-alpha.1 |
| 53 | +git push origin 4.12.0-alpha.1 |
| 54 | +``` |
| 55 | + |
| 56 | +### 5. CI Builds Automatically |
| 57 | + |
| 58 | +The GitHub Actions workflow triggers on tag push and: |
| 59 | +- Builds for all platforms (Windows, macOS, Linux) |
| 60 | +- Generates `alpha.yml`, `alpha-mac.yml`, `alpha-linux.yml` metadata |
| 61 | +- Creates a draft GitHub release marked as **Pre-release** |
| 62 | +- Publishes Linux snap to the `edge` channel |
| 63 | + |
| 64 | +### 6. Publish the Release |
| 65 | + |
| 66 | +1. Go to GitHub Releases |
| 67 | +2. Find the draft release for your version |
| 68 | +3. Review the release notes |
| 69 | +4. Click "Publish release" |
| 70 | + |
| 71 | +## How Users Opt Into Alpha |
| 72 | + |
| 73 | +### Option A: Developer Mode (Recommended for QA) |
| 74 | + |
| 75 | +1. Open Settings in the app |
| 76 | +2. Enable **Developer Mode** |
| 77 | +3. Open **About** dialog (Help > About) |
| 78 | +4. Select **Alpha (Experimental)** from the Update Channel dropdown |
| 79 | +5. Click **Check for Updates** |
| 80 | + |
| 81 | +The setting persists - users don't need to select it again. |
| 82 | + |
| 83 | +### Option B: Configuration File (For Managed Deployments) |
| 84 | + |
| 85 | +Create `update.json` in the user data directory: |
| 86 | + |
| 87 | +| Platform | Location | |
| 88 | +|----------|----------| |
| 89 | +| Windows | `%APPDATA%\Rocket.Chat\update.json` | |
| 90 | +| macOS | `~/Library/Application Support/Rocket.Chat/update.json` | |
| 91 | +| Linux | `~/.config/Rocket.Chat/update.json` | |
| 92 | + |
| 93 | +Content: |
| 94 | +```json |
| 95 | +{ |
| 96 | + "channel": "alpha" |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +For enterprise deployments where you want to force the setting: |
| 101 | +```json |
| 102 | +{ |
| 103 | + "channel": "alpha", |
| 104 | + "forced": true |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +## Version Numbering Guidelines |
| 109 | + |
| 110 | +- **Alpha**: `4.12.0-alpha.1`, `4.12.0-alpha.2`, etc. |
| 111 | +- **Beta**: `4.12.0-beta.1`, `4.12.0-beta.2`, etc. |
| 112 | +- **Stable**: `4.12.0` |
| 113 | + |
| 114 | +When promoting: |
| 115 | +- Alpha `4.12.0-alpha.5` → Beta `4.12.0-beta.1` |
| 116 | +- Beta `4.12.0-beta.3` → Stable `4.12.0` |
| 117 | + |
| 118 | +## Safety Guarantees |
| 119 | + |
| 120 | +- Stable users **never** see alpha releases (they check `latest.yml`, not `alpha.yml`) |
| 121 | +- Users must explicitly opt into alpha channel |
| 122 | +- Alpha releases are marked as "Pre-release" on GitHub |
| 123 | +- Users can switch back to stable at any time |
| 124 | + |
| 125 | +## Troubleshooting |
| 126 | + |
| 127 | +### Alpha update not showing |
| 128 | + |
| 129 | +1. Verify the release is published (not draft) |
| 130 | +2. Check that `alpha.yml` exists in the release assets |
| 131 | +3. Ensure user has selected "Alpha" channel |
| 132 | +4. Check for updates manually via About dialog |
| 133 | + |
| 134 | +### Checking current channel |
| 135 | + |
| 136 | +In Developer Mode, open About dialog - the current channel is shown in the dropdown. |
0 commit comments