Versioning and releases
How a change becomes a release (Changesets, the Version packages PR, GitHub Packages) and how the docs are deployed.
@ergasti/bricks follows semantic versioning with one pre-1.0 caveat: while the version starts with 0., a minor release can change how things look, so review each screen when you raise it. Releases are made with Changesets. The latest release is 0.5.0; the pending changesets, listed on Changelog, will be released as 0.6.0.
The flow
- Make the change on a branch and add a changeset. Run
npx changeset, pick the bump and write what changed. Each changeset is a Markdown file in.changeset/.- patch: a fix; nothing visible changes.
- minor: a new component or prop, or a corrected default look (flagged as such in the changeset).
- major: a removed or renamed prop, or a visual change projects must review.
- Open a PR. The CI workflow (
.github/workflows/ci.yml) runs on the self-hosted runners:npm run typecheck,npm test,npm run build, thennode scripts/check-package.mjs, which packs the tarball, checks its file list against theexportsmap and type-checks a small consumer project undermoduleResolutionbundlerandNodeNext. - Merge to
main. The Release workflow (.github/workflows/release.yml) runs the same four checks, then the Changesets action. With changesets pending, it opens a "Version packages" PR, or updates the one already open. That PR runschangeset version: it raises the version inpackages/bricks/package.json, writes the changesets intopackages/bricks/CHANGELOG.mdand deletes them. - Merge the "Version packages" PR. The Release workflow runs again, finds no changesets and publishes:
npm run releasebuilds the package and runschangeset publish, which publishes@ergasti/bricksto GitHub Packages (https://npm.pkg.github.com, restricted access) with the workflow'sGITHUB_TOKEN, and tags the release. - In each project, raise the
@ergasti/bricksversion and run its tests. Read Migration for every release you skip.
Pending changesets show on Changelog next to the released versions. What an app changes from one release to the next is on Migration.
Rules for a change
From the project's plan: tests with each component (render, keyboard, RTL, Arabic copy); no new runtime dependency without a reason in the changeset; nothing imports app code; a gallery entry in English and Arabic; and one changeset per work package. A guard test checks that every component or type a changeset names in backticks is exported.
Deprecations
A deprecated API carries a @deprecated tag naming its replacement, so an editor strikes it through. It keeps working until 1.0. The list is generated on Deprecated APIs.
This documentation
The docs are built by npm run docs from the package source, so they describe the code on main. The version number next to the logo is read from packages/bricks/package.json at build time, and the pending changesets are shown on Changelog.
The Docs and Storybook workflow (.github/workflows/docs.yml) checks them, and Jenkins deploys them. On every push to main, or when run by hand from Actions:
- a self-hosted runner runs
npm run docs(the site, intodocs/dist) andnpm run build-storybook, copies Storybook todocs/dist/storybook, and uploads the result as thedocs-siteworkflow artifact (kept 14 days); - when that passes on
main, it starts the Jenkins jobbricks-docs, using the repository secretsJENKINS_USERandJENKINS_API_TOKEN; until they are set, it only says the deploy is not configured; - Jenkins runs the repository's
Jenkinsfileon the application server (agentergasti-production,37.27.194.219): it builds the imagebricks-docs:<commit>fromdeploy/docs/Dockerfile(Node builds the site, nginx serves it), starts it withdeploy/docs/compose.ymlbehind Nginx Proxy Manager, keeps the three newest images for rollback, and checks that the running container is that commit and that the site and Storybook answer.
The README's "Hosting the docs" section has the one-time setup (Jenkins job, port, firewall, proxy host, secrets) and how to roll back.