Canonical Release Workflow

The canonical workflow treats the design system and its consumers as independently shipped artifacts. The design-system team releases on its own cadence; consumers bump when they need new capabilities or bug fixes.

When to use

• The design-system change is self-contained and doesn’t need active validation by a specific consumer.
• The consumer can wait for a stable release before adopting.
• This is the default for any change that doesn’t justify the overhead of preview or local-link workflows.

Sequence

In ux-prototype

1. Branch off main: git checkout -b <username>/<description>.
2. Implement the change. Follow the Storybook developer-workflow page for component and test conventions.
3. Update CHANGELOG.md with a stable entry: ## [x.y.z] - YYYY-MM-DD under one of the categories defined in .github/clq/changemap.json (Added, Changed, Fixed, etc.).
4. Push the branch. CI runs lint, typecheck, tests, VRT, and Storybook build. The validate-release job rejects pre-release entries on PRs to main, so use a stable x.y.z here.
5. Open a PR to main. Address Copilot/Codex review comments and obtain reviewer approval.
6. Merge. On the merge commit:
   • publish.yml builds and publishes the package version (extracted from the changelog entry) to GitHub Packages with dist-tag latest.
   • tag job in ci.yml creates a GitHub Release at vX.Y.Z with the changelog body as release notes.

In the consuming app (e.g. arda-frontend-app)

7. Decide to upgrade. Triggers can be: needing a new capability, a bug fix, security patch, or a routine dependency-update cycle.
8. Bump the dependency:

   npm install @arda-cards/design-system@latest

   Or pin to an exact version with --save-exact if reproducibility matters more than transparent patch upgrades.
9. Test locally that the new version doesn’t break anything (typecheck, unit tests, manual smoke).
10. Open a PR in the consumer repo with the bumped package.json + package-lock.json.
11. Merge following the consumer’s normal PR process.

Contracts

• Backwards compatibility: stable releases follow semver. Major-version bumps are reserved for breaking changes; minor for additive changes; patch for bug fixes. The .github/clq/changemap.json in ux-prototype enforces the bump category from the changelog category.
• Stable releases never carry preview suffixes: the validate-release gate in ux-prototype/.github/workflows/ci.yml rejects PRs to main whose changelog entry is a pre-release.
• latest dist-tag: only publish.yml (running on main push) updates latest. Branch publishes use other dist-tags. See version-and-tag-conventions.

Trade-offs

Pro	Con
Simple, predictable, well-understood	Slowest feedback loop — consumer can’t validate until after design-system ships
Stable releases never disappear — consumers can always pin	If a stable release breaks consumers, rollback requires a new patch release
Independent cadences — neither team blocks the other	Coordination of breaking changes happens via release notes only

When to escalate

If you’re in the middle of this workflow and discover the change actually requires consumer-side validation before shipping stable, switch to either preview publish (for asynchronous validation) or coordinated multi-PR (for synchronous gating).