Skip to Content
BBRICKSv0.7.4
Getting started

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

  1. 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.
  2. Open a PR. The CI workflow (.github/workflows/ci.yml) runs on the self-hosted runners: npm run typecheck, npm test, npm run build, then node scripts/check-package.mjs, which packs the tarball, checks its file list against the exports map and type-checks a small consumer project under moduleResolution bundler and NodeNext.
  3. 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 runs changeset version: it raises the version in packages/bricks/package.json, writes the changesets into packages/bricks/CHANGELOG.md and deletes them.
  4. Merge the "Version packages" PR. The Release workflow runs again, finds no changesets and publishes: npm run release builds the package and runs changeset publish, which publishes @ergasti/bricks to GitHub Packages (https://npm.pkg.github.com, restricted access) with the workflow's GITHUB_TOKEN, and tags the release.
  5. In each project, raise the @ergasti/bricks version 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:

  1. a self-hosted runner runs npm run docs (the site, into docs/dist) and npm run build-storybook, copies Storybook to docs/dist/storybook, and uploads the result as the docs-site workflow artifact (kept 14 days);
  2. when that passes on main, it starts the Jenkins job bricks-docs, using the repository secrets JENKINS_USER and JENKINS_API_TOKEN; until they are set, it only says the deploy is not configured;
  3. Jenkins runs the repository's Jenkinsfile on the application server (agent ergasti-production, 37.27.194.219): it builds the image bricks-docs:<commit> from deploy/docs/Dockerfile (Node builds the site, nginx serves it), starts it with deploy/docs/compose.yml behind 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.

On this page