Consider canary releases for downstream preview (deferred)

[martyy-code]

Context

Downstream consumers of @deessejs/errors (notably apps/web in the workspace) may at some point want a preview channel for testing unreleased fixes or features before they hit npm @latest. Two patterns support this:

1. Snapshot releases via Changesets: pnpm changeset version --snapshot canary produces 0.0.0-canary-<timestamp> versions published under the npm canary dist tag, then --tag canary on publish.
2. Branched prerelease mode: pnpm changeset pre enter next + a dedicated next branch + a separate workflow publish loop. Heavier, fully aligned with Changesets prerelease semantics.

Either path produces an npm-installable preview pin (npm install @deessejs/errors@canary).

We have not observed a concrete demand yet. The release engineer can already, manually, publish a one-off preview by branching off the desired commit and running pnpm changeset publish --tag preview from workflow_dispatch. That ad-hoc fallback is slow (~5 minutes per request) but accurate and zero-infrastructure.

Why defer

• YAGNI adapted. Snapshot releases in Changesets create a side-track state (mutually exclusive with the normal release flow). Until there is a concrete downstream consumer, the maintenance cost outweighs the benefit.
• Ad-hoc fallback exists. The release engineer can publish a single preview tag on demand without any new workflow.
• Cost of getting it wrong. Snapshot releases add an extra publish surface that requires its own runbook (how to graduate a snapshot to stable, how to recover if a snapshot ships accidentally as stable, how to clean up tags).

Proposed approach when the need arises

If and when a downstream consumer (most likely apps/web) requests preview versions, the recommended implementation is:

1. A canary.yml workflow triggered on a canary/* branch (or workflow_dispatch with a commit ref input).
2. It runs pnpm changeset version --snapshot canary and pnpm changeset publish --tag canary with the same trusted-publishing configuration as release.yml.
3. CONTRIBUTING.md documents the canary npm dist tag and a one-liner for consumers: npm install @deessejs/errors@canary.
4. A runbook section in docs/internal/engineering/process/releasing-a-new-version.md covering the promotion path (graduating a canary to stable) and the rollback path (removing a bad canary).

The branched-prerelease pattern (option 2) is not recommended for this package size. Snapshot releases are sufficient until the project grows past one downstream consumer.

Acceptance criteria (when implemented)

• A consumer (probably apps/web) has formally requested a preview channel — explicit ask in writing.
• The chosen canary approach has been documented in CONTRIBUTING.md and the release runbook.
• A canary publish has been demonstrated end-to-end on a non-critical commit.
• Trusted publishing is enabled for the canary workflow on npmjs.com (same publisher, canary dist tag).
• The release runbook covers promotion to stable and rollback.
• The plan in docs/internal/engineering/plans/release-system.md is updated to reflect the canary workflow as part of Section 7 (post-plan additions).

Related

• Changesets snapshot releases: Support for canary releases based on changesets?  changesets/changesets#855
• Changesets prerelease semantics: https://github.com/changesets/changesets/blob/main/docs/prereleases.md
• Past incidents that would have benefited from a canary channel: documented in docs/internal/engineering/plans/release-system.md Appendix A.

Status

Deferred. To be picked up when a concrete downstream need emerges.