​

Release Process

This page describes the current repository release flow, not an idealized future-state pipeline.

​

Current shipping model

• Pull requests are the unit of delivery.
• GitHub Actions is the source of truth for repository checks.
• apps/web, apps/app, and apps/api deploy through Vercel in the current alpha posture.
• apps/worker deploys through Railway-style deployment.
• Semver tags are used for deliberate releases.
• Runtime buildVersion is distinct from semver release version.

​

Current default checks

The repo validates:

• lint
• docs lint
• docs hygiene
• OpenAPI spec drift
• release hygiene
• docs build
• typecheck
• tests
• build

Additional hardening workflows such as dependency review and CodeQL exist, but they may depend on repository plan/configuration.

​

Release train policy

Until alpha, Switchbord uses release-train semver:

• patch for fixes, docs corrections, and release hygiene
• minor for coherent capability waves
• major only for stable 1.0.0 semantics

Do not create a minor version for every PR. A version should explain a coherent state of the repository.

​

Required release steps

For every deliberate release:

1. Update package.json to the intended version.
2. Update CHANGELOG.md with ## vX.Y.Z and factual git-backed dates.
3. Update public web changelog MDX if the release is customer-facing.
4. Update Mintlify docs for any user-visible feature or operational behavior change.
5. Run:
   pnpm release:hygiene
   pnpm lint
   pnpm --filter docs docs:hygiene
   pnpm typecheck
   pnpm test
   pnpm build
   
6. Merge the release PR.
7. Tag exactly the same version:
   pnpm release:tag
   pnpm release:tag:push
   
8. Confirm the GitHub Release was created for the matching tag.

​

Back-minting historical tags

Historical alpha versions before this policy were not consistently tagged. Do not fabricate tags. If back-minting is needed before alpha:

1. Identify the exact commit that represented that release state.
2. Verify package.json and CHANGELOG.md at that commit.
3. Create the historical tag only if the evidence is unambiguous.
4. Prefer starting strict matching at the next release train if the historical boundary is unclear.

​

Contributor guidance

• Do not assume a feature is release-ready just because it builds locally.
• If your change alters runtime behavior, update both Mintlify docs and repo-level operational docs that describe the same contract.
• If your change affects public marketing state, update the web changelog or explicitly state why not in the PR body.
• If a changelog date is not backed by git log or gh pr view, do not commit it.
• If a change would require new CI gates, document that as an explicit follow-up instead of implying it already exists.

​

Planned hardening

These are expected additions, but should be described as planned until they are live in CI:

• container builds for long-running runtimes
• migration validation
• stricter environment checks
• release environment promotion policy

​

Read next

• Versioning
• CI/CD
• Contribution Workflow