Vue - v1.0.0

This monorepo uses Changesets for versioning and publishing both packages (@artisanpack-ui/vue, @artisanpack-ui/vue-laravel) to npm under the @artisanpack-ui scope.

Overview

The release pipeline has three modes:

Both packages are linked in Changesets config, meaning they are always versioned together (a bump to one bumps both).

Prerequisites

• Trusted publishers must be configured on npmjs.com for each package (see npm docs). Each package needs trusted publisher entries for both ci.yml and snapshot.yml workflows.
• The npm organization @artisanpack-ui must exist on npmjs.com
• All packages have publishConfig.access: "public"

Stable Releases

1. Add a changeset with your PR

Every PR that changes published code should include a changeset describing what changed. Run:

npm run changeset

This walks you through:

• Which packages are affected
• Whether it's a major, minor, or patch bump
• A summary of the change (this becomes the changelog entry)

It creates a markdown file in .changeset/ (e.g. .changeset/brave-dogs-fly.md). Commit this file with your PR.

Example changeset file:

---
"@artisanpack-ui/vue": minor
---

Added new DateRangePicker component with keyboard navigation support

2. Changesets bot opens a "Version Packages" PR

When changesets land on main, the release job in ci.yml uses changesets/action to:

• Detect pending changesets
• Open (or update) a PR titled "chore: version packages"
• That PR bumps version fields in each package.json and updates CHANGELOGs

3. Merge the Version Packages PR to publish

Merging the "Version Packages" PR triggers the release job again. This time there are no pending changesets, so the CI pipeline builds all packages first (npm run build), then npx changeset publish runs which:

• Publishes each changed package to npm with the latest tag (using the already-built artifacts)
• Creates GitHub releases with changelog content
• Provenance attestation is included automatically (via id-token: write permission)

Summary of the flow

PR with changeset → merge to main → bot opens "Version Packages" PR → merge that → npm publish

Snapshot Releases

Snapshots let you publish a test version without affecting the stable latest tag. Useful for:

• Testing unreleased changes in a real project
• Sharing pre-release builds with collaborators
• CI/CD integration testing

How to trigger

1. Go to Actions tab in GitHub
2. Select the "Snapshot Release" workflow
3. Click "Run workflow"
4. Optionally set a tag name (defaults to snapshot, could be canary, next, dev, etc.)

What happens

The workflow:

1. Installs dependencies and builds all packages
2. Runs the full test suite
3. Runs changeset version --snapshot <tag> which creates temporary snapshot versions in the format 0.0.0-<tag>-<YYYYMMDDHHMMSS> (e.g. 0.0.0-snapshot-20260330120000). To use the current package version as the base instead, set snapshot.useCalculatedVersion: true in .changeset/config.json.
4. Runs changeset publish --tag <tag> which publishes to npm under the specified dist-tag

Installing a snapshot

npm install @artisanpack-ui/vue@snapshot
# or whatever tag you used:
npm install @artisanpack-ui/vue@canary

Snapshot versions do not affect the latest tag, so npm install @artisanpack-ui/vue still gets the latest stable version.

Local Development Workflow

Check what would be released

npx changeset status

This shows which packages have pending changesets and what version bumps are queued.

Preview version bumps locally (dry run)

npx changeset version

This updates package.json versions and CHANGELOGs locally. You can inspect the changes and then git restore . to revert if you were just checking.

Convenience scripts

Changelogs

Changelogs are auto-generated per package from changeset descriptions. We use @changesets/changelog-github which includes:

• Links to the PR that introduced each change
• Links to the commits
• Author attribution

Changelog files are created/updated at packages/<name>/CHANGELOG.md when the "Version Packages" PR is created.

Provenance

All published packages include npm provenance attestation. This means:

• Each published package is cryptographically linked to the GitHub Actions run that built it
• Users can verify the package came from this repo's CI, not a compromised local machine
• The id-token: write permission in the release workflow enables this

You can verify provenance on npmjs.com — published packages will show a green "Provenance" badge.

Linked Versioning

Both packages are linked in .changeset/config.json:

"linked": ["@artisanpack-ui/vue", "@artisanpack-ui/vue-laravel"](https://docs.artisanpackui.dev/documentation/vue/"@artisanpack-ui-vue",-"@artisanpack-ui-vue-laravel")

This means if either package gets a minor bump, both packages are bumped to the same minor version. This keeps versions in sync across the ecosystem so users don't have to worry about version matrix compatibility.

Troubleshooting

"Version Packages" PR not appearing

• Make sure there are .changeset/*.md files (not just config.json and README.md) on main
• Check the release job logs in GitHub Actions

Publish fails with auth error

• Verify trusted publishers are configured on npmjs.com for each package
• Each package needs entries for both ci.yml and snapshot.yml workflow filenames
• Ensure the workflow has id-token: write permission (required for OIDC)

Snapshot version looks wrong

• By default, Changesets generates snapshot versions as 0.0.0-<tag>-<YYYYMMDDHHMMSS> (e.g. 0.0.0-snapshot-20260330120000)
• To use the current package version as the base (e.g. 1.2.3-snapshot-...), set snapshot.useCalculatedVersion: true in .changeset/config.json

Provenance attestation fails

• Ensure the workflow has id-token: write permission
• Provenance only works in GitHub Actions, not from local machines