Release

Changesets, the version pull request, and what a release publishes.

main is the only long-lived branch. Work happens in short-lived branches that are merged by squash; main is always releasable.

Changesets

A pull request that changes what @formdef/core ships adds a changeset:

pnpm changeset

It names the bump, patch, minor or major, and one line for the changelog, written for the people who use the package. A change to the documentation, the tests or the private packages needs none.

Previews

Every pull request from a branch of this repository publishes a preview of @formdef/core through pkg.pr.new. A comment on the pull request shows the command that installs it, so a change can be tried in a project before it is released. Pull requests from forks get none, and neither does the version pull request.

Installing the registry

Before a release, a probe installs every item of the shadcn registry into a new shadcn project, the way a user would, and compiles and builds that project:

pnpm --filter @formdef/shadcn probe:install

It builds the registry and @formdef/core, serves both from local servers, and fails when a file does not land where components.json says, when the CLI changes the project’s own lib/date.ts, or when the project does not compile. It needs the network for the shadcn CLI and its primitives, so it runs by hand and not in CI.

Versions

Every push to main runs the release workflow. What it does depends on what main holds:

  • Changesets: it opens or updates the "Version Packages" pull request. That pull request raises the version, writes the changelog and deletes the changesets. Since the workflow's own token opened it, its checks wait until a maintainer selects "Approve workflows to run" on it.
  • A version not yet on npm, after the version pull request is merged: it builds and packs @formdef/core and publishes it once a maintainer approves the run in the npm environment. The package is published through npm's trusted publishing, with provenance and without a stored token; the workflow then tags the release and creates the GitHub release.
  • Neither: nothing.

The widgets of the shadcn registry are not versioned on npm: the documentation site serves them, and shadcn add fetches the version that site was built from.

The documentation site

The documentation and the registry are exported as static files and served by nginx from a Docker image. After each release of @formdef/core, the release workflow builds that image from the same commit, tags it with the version and deploys it, so the site and the registry always match the package on npm. The deploy never writes the server's ~/docs/.env; an admin creates it before the first deploy, and it may be empty.

A fix to the documentation between two releases goes out by starting the "Docs" workflow by hand: without a tag it builds and deploys main; with the tag of an image built before, such as 0.1.0, it deploys that image again. The image builds locally the same way:

docker build -f apps/docs/Dockerfile --build-arg DOCS_URL=http://localhost:3010 -t formdef-docs .