Current State:

Decouple versions from git tags, using deployment channels and S3 as source of truth:

Continue using CalVer: YYYY.M.PATCH

Stable Channel (Incremental within month, resets on month change):

October 2025:
  2025.10.1 → 2025.10.2 → 2025.10.3

November 2025 (month changes, patch resets):
  2025.11.1 → 2025.11.2

January 2026 (year changes):
  2026.1.1 → 2026.1.2

Dev Channel (Based on Stable):

Scenario 1: stable=2025.10.1, no dev version
→ dev=2025.10.1-dev.1

Scenario 2: stable=2025.10.1, dev=2025.10.1-dev.1
→ next dev=2025.10.1-dev.2 (increment)

Scenario 3: stable=2025.10.2, dev=2025.10.1-dev.3
→ next dev=2025.10.2-dev.1 (reset to new stable base)

Version NOT committed to package.json - Auto-calculated in GitHub Actions and set temporarily via scripts/set-desktop-version.mjs during build (same as current approach)

Updated workflow: .github/workflows/release-desktop.yml

Triggers: Manual dispatch only (no automatic tag-based releases):

on:
  workflow_dispatch:
    inputs:
      channel:
        type: choice
        options: [dev, stable]
        required: true
        default: 'dev'

Navigate to: Actions → Release - Desktop App (Unified) → Run workflow

Select:

Process:

Update existing Docker workflows for channel-based deployment:

Current workflows:

Changes needed:

Web and desktop share same version - calculated once, used for both

# Current stable: 2025.10.1
# Goal: Release 2025.10.2

# 1. Merge changes to main
git checkout main
git pull
git push

# 2. Manually trigger release via GitHub Actions UI
# Navigate to: Actions → Release - Desktop App (Unified) → Run workflow
# Select:
#   - Branch: main
#   - Channel: stable

# 3. GitHub Actions automatically:
#    - Calculates next version (2025.10.2)
#    - Runs tests
#    - Builds for all platforms
#    - Publishes to S3 stable/latest/
#    - Archives to S3 stable/archive/2025.10.2/
#    - Creates git tag 2025.10.2
#    - Creates GitHub prerelease
#    - Updates latest.json

# 4. Users on auto-update get 2025.10.2

# Version automatically calculated based on:
# - Current date: 2025.10
# - Latest stable from S3: 2025.10.1
# - Result: 2025.10.2 (patch increment)

# Current stable: 2025.10.2
# Critical bug discovered

# 1. Create hotfix branch
git checkout -b hotfix/critical-bug main

# 2. Fix the bug
# ... make changes ...
git commit -m "fix: critical bug"

# 3. Merge to main
git checkout main
git merge hotfix/critical-bug
git push

# 4. Manually trigger release
# GitHub Actions UI → Run workflow
#   - Branch: main
#   - Channel: stable

# 5. GitHub Actions automatically:
#    - Calculates version: 2025.10.3 (increments from 2025.10.2)
#    - Builds and releases
#    - Creates tag 2025.10.3
#    - Users get 2025.10.3 via auto-update

# Current stable: 2025.10.2
# Current dev: 2025.10.2-dev.4
# Want to test new feature

# 1. Merge feature to main
git checkout main
git merge feat/new-feature
git push

# 2. Manually trigger dev release
# GitHub Actions → Run release-desktop.yml
#   Input: channel = dev

# 3. GitHub Actions automatically:
#    - Calculates version: 2025.10.2-dev.5
#    - Builds for all platforms
#    - Publishes to S3 dev/latest/
#    - Archives to S3 dev/archive/2025.10.2-dev.5/
#    - Updates RELEASES.json with currentRelease: 2025.10.2-dev.5
#    - NO GitHub release created

# 4. Team tests 2025.10.2-dev.5 internally

# Current stable: 2025.10.2
# Current dev: 2025.10.2-dev.7
# Dev build tested and ready for stable

# Manually trigger stable release
# GitHub Actions UI → Run workflow
#   - Branch: main
#   - Channel: stable

# GitHub Actions automatically:
#   - Calculates version: 2025.10.3
#   - Builds and releases
#   - Creates tag 2025.10.3
#   - Creates GitHub prerelease

# Next dev build after stable 2025.10.3
# Will auto-calculate as 2025.10.3-dev.1 (reset)

# Current date: October 31, 2025
# Current stable: 2025.10.3
# Current dev: 2025.10.3-dev.2

# === November 1, 2025 arrives ===

# Create first November release
git checkout main
git pull

# Manually trigger release
# GitHub Actions UI → Run workflow
#   - Branch: main
#   - Channel: stable

# GitHub Actions automatically:
#    - Detects current month (November = 11)
#    - Fetches latest stable from S3: 2025.10.3 (October)
#    - Resets patch to 1 for new month
#    - Version: 2025.11.1 ✓
#    - Builds and publishes
#    - Creates git tag 2025.11.1 AFTER build

# Next release in November
# Trigger workflow again → calculates 2025.11.2

# Next dev build after month change
# GitHub Actions UI → Run workflow
#   - Branch: main
#   - Channel: dev
# Calculates: 2025.11.1-dev.1 (reset to new month base)

# === January 2026 arrives ===

# First release of new year
# Trigger workflow → calculates 2026.1.1 (year and month change, patch resets)

Goal: Update scripts and test version calculation logic

Validation:

Goal: Create unified release workflow alongside existing workflows

Validation:

Goal: Switch production desktop releases to new workflow

Validation:

Goal: Update Docker workflows to use calculated versions

Validation:

Goal: Complete documentation and train team

Validation:

Goal: Remove old workflows and clean up

Validation:

✅ Unified workflow - One workflow for dev and stable, easier to maintain ✅ Faster dev testing - Manual trigger instead of scheduled, build only when needed ✅ Auto version calculation - No manual version management in package.json ✅ Clear separation - Dev vs stable clearly defined by channel

✅ Manual control - All releases triggered manually (no tag dependency) ✅ Incremental versions - Stable versions always increment (2025.10.1 → 2025.10.2) ✅ Hotfix friendly - Just trigger workflow, version auto-calculated ✅ GitHub prereleases - Automatically created for stable releases ✅ Git tags as byproduct - Tags created after successful builds (not required)

✅ Less CI waste - No scheduled builds, only on-demand dev builds ✅ Clear audit trail - S3 JSON files as source of truth, git tags optional ✅ Rollback ready - Previous versions archived in S3 ✅ Channel isolation - Dev and stable completely separate ✅ No git dependency - Version calculation entirely based on S3 state

Mitigation:

Mitigation:

Mitigation:

Mitigation:

Yes. but the tag gets added AFTER the release is made. this happens when we create the release in Github.

Yes. we can make sure the stable channel will only gets generated from the main branch.

Only maintainers or anyone with "Write" access to the repo. so is safe to rely on manual triggers (workflow_dispatch) on our repo. only Maintainers will be able to trigger releases.