Release policy

Today Canvas Kit uses three release channels: snapshot, beta, and stable. Each channel is published to both AWS CodeArtifact and GitHub Packages. The channels are registry surfaces, not long-term dependency specs. Automation may select a channel, but consuming repos should commit exact resolved versions and lockfile updates.

Branch model

• Feature work starts from origin/dev and lands in dev by PR.
• release/X.Y is optional. Cut it only when the next minor line needs repeated beta candidates while dev continues accepting unrelated work.
• main is stable-only. Direct human commits to main are prohibited; the stable release workflow's mechanical version commit is the exception.
• After stable publish, the release workflow opens a main → dev sync-back PR so consumed changesets and version files return to the integration branch.
• Changesets keeps baseBranch set to main intentionally. Development starts from dev, but release math is compared against the last stable release state on main.

Dist-tags

Snapshot

Snapshot is for continuous validation from dev. A dev push with pending changesets should:

1. Run changeset version --snapshot in CI.
2. Build packages from the post-snapshot tree.
3. Publish with --tag snapshot --no-git-tag to both registries.
4. Discard the temporary package-version rewrite.

Snapshots do not consume .changeset/*.md files. The same changesets keep feeding snapshots until they are consumed by a stable release.

The snapshot workflow also moves the legacy dev dist-tag to the same versions as a compatibility alias. New automation should select exact snapshot versions rather than committing @dev or @snapshot ranges.

Beta

Beta is a release candidate, not the default integration channel. Publish beta from an exact reviewed SHA or from a release/X.Y branch when downstream repos need to validate the next stable line before latest moves.

Beta follows the same temporary-version rule as snapshots: rewrite to X.Y.Z-beta.N in CI, build, publish with --tag beta --no-git-tag to both registries, then discard the rewrite. It does not consume changesets.

Stable

Stable is the only production-consumed channel. A stable release happens after a reviewed dev → main or release/X.Y → main PR merges.

The stable workflow:

1. Runs changeset version.
2. Commits package.json, CHANGELOG.md, and consumed changeset deletion to main.
3. Builds packages from the release commit.
4. Publishes latest to both registries.
5. Pushes release git tags.
6. Opens a main → dev sync-back PR.

Do not bump package.json to 2.2.0-unreleased after stable release. Committed versions stay at the last release state until Changesets computes and commits the next stable release version.

Git tags

Do not create git tags for snapshots. Do not create git tags for beta by default. Stable publishes push the release tags after the registry publish succeeds.

Today the release workflow uses Changesets-generated per-package tags such as @todayai-labs/tck@2.1.0. Because the fixed SDK group releases in lockstep, a future workflow may replace those with a single compatibility-group tag: tck@2.1.0 for stable, and tck@2.1.0-beta.1 only for explicitly archived beta candidates.

Changesets

Every SDK-observable change needs a changeset. The fixed SDK group moves in lockstep:

• @todayai-labs/tck
• @todayai-labs/tck-widget-utils
• @todayai-labs/tck-host
• @todayai-labs/tck-bundler
• @todayai-labs/tck-bundle-server
• @todayai-labs/tck-bundle-format
• @todayai-labs/tck-preview
• @todayai-labs/create-widget

The highest bump in the pending changeset set wins for the whole group. A single major changeset ships all eight packages at the new major version, so major releases require explicit team alignment and consumer audit.

The release PR must include generated release-plan evidence, for example changeset status output, showing exact packages and bump levels.

Downstream automation

TCK publish workflows may trigger dependency-update automation in today-platform-web.

Recommended payload:

{
  "distTag": "snapshot",
  "version": "2.1.0-snapshot.20260605050326.0ebd2b1",
  "packages": ["@todayai-labs/tck", "@todayai-labs/tck-host", "@todayai-labs/tck-bundle-format"],
  "tckSha": "0ebd2b1cd8144380444a79aedc6ed7b58ed29f4a",
  "releaseSha": "0ebd2b1cd8144380444a79aedc6ed7b58ed29f4a"
}

Receiver rules:

• Open a PR against web dev, never web main.
• Update only packages actually consumed by web.
• Commit exact versions and the lockfile. Do not commit dist-tag ranges for snapshot, beta, or legacy dev.
• Snapshot and beta PRs are validation PRs. Stable PRs are the normal dependency-update path after latest moves.