Skip to content

Release Process

Ankit Upadhyay edited this page Aug 25, 2026 · 4 revisions

Release Process

How Yosemite Crew actually ships today. This documents the versioning already in use across tags and GitHub Releases - it does not introduce a new scheme.

Canonical source: RELEASING.md at the repository root. This page summarizes it for browsability; if the two differ, the repo file wins. Desktop specifics live in apps/desktop/RELEASE.md.

Branch model

  • dev - integration branch. All PRs target dev.
  • main - release-ready. Cut a release by merging dev into main once CI is green, then tagging on main.
  • Hotfix - branch from main, fix, patch-tag directly (skip the dev queue for the fix), then back-merge into dev so the fix isn't lost on the next release cut.

The promotion model is machine-enforced

  • promotion-guard.yml only allows dev as the head branch for PRs into main. Bot PRs that open against main (e.g. Dependabot security updates, which always target the default branch) are automatically retargeted at dev; a human can override for a genuine direct-to-main change by applying the main-direct label.
  • back-merge.yml opens a back-merge PR into dev on every push to main, so dev always contains main and "is everything promoted?" stays answerable by ancestry rather than forensics.

Deploying the backend API

The API hosts deploy via deploy-api.yml - deliberately a manual workflow_dispatch with a dev/production environment choice and per-host concurrency locking (deploys run migrations against the live database, so a deploy is a decision, not a side effect of merging).

Ordering rule: deploy the API before promoting dev into main. Merging alone deploys nothing to the API hosts, so a green main says nothing about what is actually running.

Two release shapes

Different apps ship on different cadences to different targets, so there is no single unified release mechanism:

App Mechanism Trigger
apps/frontend / PIMS (web) Continuous deployment plus a versioned tag line Every push to main/dev touching frontend paths auto-deploys (cd-frontend.yaml). Separately, pims-vX.Y.Z-beta tags mark named release points for changelog purposes - deployment doesn't wait on the tag. Tagging is manual. (Older tags used the pms-v spelling; pims-v is current going forward.)
apps/backend Discrete tagged release Manual: tag backend-vX.Y.Z[-beta]; the release-notes workflow (below) fills the GitHub Release body. Artifact build/publish is not CI-automated; the running API is updated separately via deploy-api.yml (above).
apps/mobileAppYC Discrete tagged release, CI-built Tag mobile-vX.Y.Z → mobile-release.yml builds and uploads to TestFlight and the Play internal track. Promotion to the public App Store / Play production remains a manual console step.
apps/desktop Discrete tagged release, CI-built Plain semver tag vX.Y.Z[-beta.N] pushed on main → desktop-release.yml opens a draft release, builds and signs both installers (macOS Developer ID + notarization; Windows via Azure Artifact Signing), then publishes. Desktop deliberately does not use a product-prefixed tag: electron-updater drops any release whose tag is not valid semver, so desktop-v* would make releases invisible to the updater. A verify job fails the run if the tag doesn't match apps/desktop/package.json or isn't reachable from main. Test builds go through workflow_dispatch.

Each component versions independently with SemVer plus a -beta pre-release suffix while stabilizing.

package.json versions are NOT synced to tags for backend/frontend/mobile (e.g. apps/backend/package.json may read 0.0.0) - the git tag is the source of truth for those components. apps/desktop is the explicit exception: the build derives the installer name, embedded version, and updater metadata from apps/desktop/package.json, so its version must be bumped first and the tag must match it exactly - the verify job enforces this. See RELEASING.md and apps/desktop/RELEASE.md.

For orientation, the newest tag per component as of 2026-08: mobile-v1.6.1, v0.1.0-beta.4 (desktop), backend-v2.3.0-beta, pims-v2.3.0-beta.

Release checklist

  1. Confirm CI is green on main for the commit you're about to tag (and, for anything touching the API, that the API host has been deployed - see above).
  2. Pick the version per SemVer (breaking → major, new capability → minor, fix-only → patch), keeping -beta while pre-1.0. Desktop: bump apps/desktop/package.json first.
  3. Tag with the component prefix (plain v for desktop): git tag backend-v1.4.0-beta && git push origin backend-v1.4.0-beta.
  4. If no GitHub Release exists for the tag, create one: gh release create backend-v1.4.0-beta --title "backend v1.4.0-beta". The release-notes workflow fills in the body automatically.
  5. Smoke-test the deployed/published artifact.

Release notes are generated, not hand-written

Commit messages are already enforced into <type>(<scope>): <subject> by commitlint and the PR-title gate, so every commit reaching main carries the structure a changelog needs. cliff.toml configures git-cliff to group commits by Conventional Commit type, and release-notes.yml runs on every *-v* tag push: it finds the previous tag sharing the same component prefix, runs git-cliff over the range, and attaches the result to the GitHub Release (creating it first if needed). Nothing is committed back to main/dev.

Preview locally before tagging:

git-cliff <previous-tag>..HEAD --config cliff.toml

What this does not (yet) do

  • Backend / PIMS releases are still manually tagged - the automation covers the notes (all components) and the artifact build/publish (desktop and mobile), not the decision of when/what to release.
  • package.json versions are not wired to tags (desktop excepted, where they must match by hand) - full sync would need per-app release automation (Changesets / release-please), left for a future ADR.

Where to find release notes

GitHub Releases - bodies auto-generated from Conventional Commits by release-notes.yml on tag push.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally