Skip to content

Release Workflow

This project uses a dual-channel release strategy with two independent release tracks.

Release Channels

Alpha Channel (main branch)

  • Branch: main
  • Release format: v0.x.0-alpha
  • Trigger: Release-please PR merged to main
  • Deployment target: dev environment
  • Use case: Continuous development, testing new features

Stable Channel (release branch)

  • Branch: release
  • Release format: v0.x.0 (no alpha suffix)
  • Trigger: v* tag pushed to release branch (manually, see Step 3)
  • Deployment target: prod environment
  • Use case: Production releases after alpha testing

Release Process

Step 1: Alpha Release (Automatic)

  1. Make commits to main branch using conventional commits (feat:, fix:, etc.)
  2. Release-please detects version-bumping commits and opens a release PR automatically
  3. Merge the release-please PR → creates v0.x.0-alpha tag and GitHub release
  4. deploy-release.yml triggers on the tag → deploys to dev environment

Step 2: Test on Dev

  1. Verify smoke tests pass on dev
  2. Validate features work as expected
  3. Review deployment logs for issues

Step 3: Stable Release (Manual — 5 steps)

IMPORTANT: Release-please does NOT manage the stable release automatically. The release branch does not receive conventional commits (only merge commits), so release-please cannot compute a version bump. The stable release must be done manually:

  1. Open PR from main → release. Expect conflicts in CHANGELOG.md, package.json, and .release-please-manifest.json — resolve all three by taking main's version string.

  2. Merge the PR (requires admin override — branch protection is on).

  3. Fix the manifest on the release branch — set .release-please-manifest.json to the last stable version (e.g. 0.20.0), NOT the alpha version. Commit and push directly to release. This step is needed because the PR brought over the alpha manifest, and without this correction release-please would propose the wrong next version if ever triggered.

  4. Create and push the stable tag manually:

git checkout release && git pull origin release
git tag -a v0.21.0 -m "Version 0.21.0"
git push origin v0.21.0

This triggers deploy-release.yml → prod deploy, and deploy-infrastructure.yml → prod infra.

  1. Create the GitHub release:
gh release create v0.21.0 --title "v0.21.0" --latest --notes "..."
  1. Update manifest to the new stable version and push:
# Set .release-please-manifest.json to "0.21.0"
git add .release-please-manifest.json && git commit -m "chore: update manifest to 0.21.0 after stable release"
git push origin release

Why Release-Please Doesn't Auto-Create Stable Releases

Release-please requires conventional commits (feat:, fix:) on the target branch to compute a version bump. When main is merged into release, the resulting commit is chore: promote ... — which release-please ignores. The feature/fix commits are squashed into the merge and not visible to release-please on the release branch.

Do not attempt to trigger release-please via workflow_dispatch on the release branch — it will either do nothing or propose the wrong version if the manifest is not correct.

Merge Conflict Resolution (main → release)

Conflicts always occur in these three files. Resolution:

File Resolution
.release-please-manifest.json Take main's value (the alpha version)
package.json Take main's version string
CHANGELOG.md Keep main's new entries at the top, retain release's existing content below

Release-Please Configuration

Defined in release-please-config.json. Two release-please branch configs exist:

  • main → alpha releases (automated via release-please PRs)
  • release → stable releases (effectively unused; stable releases are manual)

Commit Message Convention

Release-please uses conventional commits on main:

  • feat: → Minor version bump (v0.x.0)
  • fix: → Patch version bump (v0.x.1)
  • feat!: → Major version bump (v1.0.0)

Emergency Hotfixes

For urgent prod fixes:

  1. Create hotfix branch from release (e.g. hotfix/bug-xyz)
  2. Make fix and test
  3. PR to release branch
  4. Manually tag and release (same as Step 3 above, but patch version: v0.21.1)
  5. Cherry-pick or PR the fix back to main to keep branches in sync