Dispatch Release

Overview

The Cartridge Controller uses a two-phase release process:

1. Dispatch: Creates a release preparation PR with version bumps
2. Publish: Merges PR triggers npm publish and GitHub release

Release Types

Type	Tag	Use Case
latest	Production	Stable releases for general use
prerelease	Beta/RC	Testing releases before stable

Dispatching a Release

Step 1: Determine Version

Follow semantic versioning:

• Major (1.0.0): Breaking changes
• Minor (0.1.0): New features, backward compatible
• Patch (0.0.1): Bug fixes, backward compatible

Check current version:

jq -r '.version' packages/controller/package.json

Step 2: Dispatch via GitHub CLI

# For a production release
gh workflow run release-dispatch.yml \
  -f version="X.Y.Z" \
  -f tag="latest"

# For a prerelease
gh workflow run release-dispatch.yml \
  -f version="X.Y.Z-beta.1" \
  -f tag="prerelease"

Step 3: Monitor Workflow

# Watch the workflow run
gh run watch

# Or list recent runs
gh run list --workflow=release-dispatch.yml

Step 4: Review the Release PR

The workflow creates:

1. A PR titled "Prepare release: X.Y.Z" (or "Prepare prerelease: X.Y.Z")
2. A draft GitHub release

# Find the PR
gh pr list --head prepare-release
# or
gh pr list --head prepare-prerelease

# Review the PR
gh pr view <PR_NUMBER>

The changelog will be auto-generated by the changelog-generation.yml workflow.

Step 5: Merge to Publish

Once the release PR is reviewed and approved:

gh pr merge <PR_NUMBER> --merge

This triggers release.yml which:

1. Builds all packages
2. Publishes to npm (@cartridge/controller, @cartridge/connector)
3. Finalizes the GitHub release with changelog

Verifying the Release

After merge, verify:

# Check npm
npm view @cartridge/controller version
npm view @cartridge/connector version

# Check GitHub releases
gh release list --limit 5

# View specific release
gh release view v<VERSION>

Workflow Files

File	Purpose
release-dispatch.yml	Initiates release, creates PR and draft release
changelog-generation.yml	Auto-generates changelog for release PRs
release.yml	Publishes to npm when release PR merges

Common Scenarios

Cancel a Release

If you need to cancel before merge:

# Close the PR without merging
gh pr close <PR_NUMBER>

# Delete the draft release
gh release delete v<VERSION> --yes

Hotfix Release

For urgent fixes:

1. Create fix on main (or cherry-pick)
2. Dispatch patch version release
3. Fast-track review and merge

Failed Release

If npm publish fails:

1. Check the release.yml workflow logs
2. Fix the issue
3. Re-run the workflow or manually dispatch release.yml

gh workflow run release.yml

Example: Full Release Flow

# 1. Check current version
jq -r '.version' packages/controller/package.json
# Output: 0.9.5

# 2. Dispatch next minor version
gh workflow run release-dispatch.yml -f version="0.10.0" -f tag="latest"

# 3. Wait for PR creation
sleep 30
gh pr list --head prepare-release

# 4. Review changelog (auto-generated)
gh pr view --web  # Opens in browser

# 5. After review, merge
gh pr merge --merge

# 6. Verify publication
npm view @cartridge/controller version
# Output: 0.10.0

Required Permissions

• GitHub token with contents: write and pull-requests: write
• npm token (configured as NPM_TOKEN secret)
• CREATE_PR_TOKEN secret for PR creation