Release Flow

Crown packages use a two-channel release flow:

• develop publishes beta snapshots to the beta dist-tag.
• main publishes stable releases to the latest dist-tag.

Use beta releases to validate changes in downstream apps before promoting those changes to a stable release.

Release channels

The root scripts are:

bun run version       # changeset version
bun run release       # turbo run build && changeset publish
bun run release:beta  # changeset publish --tag beta --no-git-tag

CI decides which script path to use from the branch that received the push.

Choose patch, minor, or major

Every package output or public API change needs a changeset. Pick the bump by consumer impact.

Rule of thumb: if consumers get new identifiers, use at least minor. If an existing identifier disappears, moves, or changes meaning in a breaking way, use major.

@kingpowerclick/crown-css and @kingpowerclick/crown-utils are in a fixed Changesets group, so they release at the same stable version. Include @kingpowerclick/crown-tailwind only when its package output or public API changes.

Write a changeset

Create a file under .changeset/ with a short, unique name. The frontmatter declares which packages should be released and what bump each package needs.

Patch example:

---
"@kingpowerclick/crown-css": patch
"@kingpowerclick/crown-utils": patch
---

Fix primary button hover token value.

Minor example:

---
"@kingpowerclick/crown-css": minor
"@kingpowerclick/crown-utils": minor
---

Add semantic roles for loyalty status colors.

Major example:

---
"@kingpowerclick/crown-css": major
"@kingpowerclick/crown-utils": major
---

Rename deprecated semantic color roles.

If the Tailwind package changes too, include it in the same changeset:

---
"@kingpowerclick/crown-css": minor
"@kingpowerclick/crown-utils": minor
"@kingpowerclick/crown-tailwind": minor
---

Add theme variables and Tailwind variants for loyalty status colors.

Documentation-only changes do not need a changeset.

Publish a beta

Beta publishing is automatic after a PR lands on develop, as long as the repo has at least one pending .changeset/*.md file.

1. Start from develop.

git checkout develop
git pull
git checkout -b feature/<short-name>

2. Make the package changes and add the changeset.

3. Verify locally.

bun install
bun run build
bun run test

4. Commit, push, and open a PR to develop.

git add .changeset/<file>.md <changed-files>
git commit -m "feat(css): describe the release change"
git push -u origin feature/<short-name>
gh pr create --base develop

5. Merge the PR into develop.

On the develop push, CI builds, tests, verifies committed generated outputs, then stamps the published packages with:

<current-stable-base>-beta.<github_run_number>

For example, if @kingpowerclick/crown-css is currently 1.0.0 and the workflow run number is 42, CI publishes:

1.0.0-beta.42

CI then runs bun run release:beta, which publishes to the beta dist-tag without creating git tags.

Install a beta in a downstream app with:

bun add @kingpowerclick/crown-css@beta

Beta publishing does not consume changesets, does not update changelogs, and does not commit package version changes back to develop.

Publish a stable release

Stable publishing happens through main.

1. Wait until the accumulated changes on develop are ready to ship.

2. Open a PR from develop to main.

3. Merge the PR into main.

4. The push to main runs the Changesets action. If there are pending changesets, the action opens a "Version Packages" PR.

5. Review the "Version Packages" PR. It should:

• Bump package version fields according to the pending changesets.
• Regenerate package CHANGELOG.md files.
• Remove the consumed .changeset/*.md files.

6. Merge the "Version Packages" PR.

7. CI runs bun run release and publishes stable packages to the latest dist-tag.

Consumers can then install the stable package normally:

bun add @kingpowerclick/crown-css

How the automation works

The release workflow runs on pushes to develop and main.

Before either publish path, CI:

1. Installs dependencies with bun install --frozen-lockfile.
2. Runs bun run build.
3. Runs bun run test.
4. Checks generated outputs for crown-css, crown-utils, and crown-tailwind.

Then the branch determines the publish behavior:

The packages publish to GitHub Packages using the @kingpowerclick registry and restricted package access.