Publishing guide

Release readiness

Use this runbook to publish Snurble prereleases, move consumers onto registry installs, and enforce the gates that keep later adoption safe. workv2 remains the foundation reference; mattriley.tools is the first proving consumer.

Manual prerelease contract

Why the first publishing path stays manual

Start with a manual prerelease so the package contents, versioning contract, and registry-auth workflow are all explicit before they are automated. The first proving consumer run happens when published prereleases are installed in mattriley.tools rather than from local tarballs or workspace links.

The operator path is a manual prerelease using a prerelease dist-tag and explicit package versions.

Derive NEXT_VERSION from the current published package version and use the same prerelease string for both packages so consumer manifests and rollback notes stay easy to reason about.

Operator runbook

NEXT_VERSION=<next-prerelease-version>

pnpm run validate
pnpm --dir packages/tokens version "$NEXT_VERSION" --no-git-tag-version
pnpm --dir packages/ui-astro version "$NEXT_VERSION" --no-git-tag-version
mkdir -p artifacts/prerelease
pnpm --dir packages/tokens pack --pack-destination ./artifacts/prerelease
pnpm --dir packages/ui-astro pack --pack-destination ./artifacts/prerelease

# export NODE_AUTH_TOKEN with write:packages access for the @matt-riley scope first
pnpm --dir packages/tokens publish --tag next --no-git-checks --registry https://npm.pkg.github.com
pnpm --dir packages/ui-astro publish --tag next --no-git-checks --registry https://npm.pkg.github.com

Consumer install contract

Consumers must install real prerelease versions from the package registry and commit those versions in their manifest and lockfile. Do not leave file: refs or local tarball dependencies in committed consumer state. mattriley.tools is the first proving consumer; workv2 and later adopters can move onto the shipped surface once they are ready to validate against published prereleases.

Public imports stay on package entrypoints only, and consumer-owned shell concerns remain local unless Snurble has explicitly absorbed them.

Later adopters should follow the same contract only after mattriley.tools has rerun its validation surface against published prerelease versions and the package contract has proven stable outside the design-system workspace.

Registry install example

@matt-riley:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

pnpm add @matt-riley/design-tokens@<prerelease> @matt-riley/ui-astro@<prerelease>

Rollback path

If a prerelease is bad, do not reuse the same version. Revert the consumer back to the last known-good package versions, publish a newer prerelease, and rerun the consumer validation surface before resuming rollout.

Adoption gates

Adoption gates for later adopters

packed artifacts contain only intentional runtime and documentation files
the manual prerelease path is documented with versioning and auth expectations
mattriley.tools (the first proving consumer) has rerun its validation surface against published prereleases
later adopters can follow the same public import and install contract
workv2 or any later adopter has validated its own integration against the same published prereleases before rollout

Automation follow-on

Automate only after the runbook stays stable

Shared release-please and GitHub Packages workflow wiring should encode this exact manual contract rather than invent a different release process. Automation comes after package contents, consumer ergonomics, and rollback expectations are all understood from real prerelease use.

That keeps the automated path aligned with the operator runbook instead of drifting away from the behavior that consumers already validated.