Resources

Release process

Current: 2.4.0

A design system is infrastructure, and infrastructure has to be boring to upgrade. The process is built around one promise: nothing breaks without warning, and nothing is removed without a path off it.

VersioningPermalink to this section

Semantic versioning, applied strictly. The version number is a contract about how much work an upgrade will be.

Change	Bump	Example
Something is removed or renamed	Major	The flat palette export removed in 2.0.0
A prop's default changes	Major	Tooltip's delay would be a minor; a default variant change would not
A new component or variant	Minor	The command menu in 2.4.0
A new token	Minor	--surface-sunken in 2.3.0
A token value changes	Minor, or major if it changes meaning	A brand hue adjustment is minor; repurposing a token is major
A bug fix with no API change	Patch	Select trigger truncation in 2.4.0

Visual changes are not automatically patches

A change that alters how something looks can break a consumer’s layout even when no API changed. If a component’s intrinsic size or spacing changes, it ships as a minor release with a changelog entry naming the affected component.

CadencePermalink to this section

Predictable timing matters more than fast timing. Teams plan upgrades around a schedule they can rely on.

Release	Frequency	Contains
Patch	As needed	Bug fixes only. Safe to take immediately.
Minor	Roughly every six weeks	New components, variants and tokens. Backwards compatible.
Major	At most twice a year	Removals and renames, always with a codemod and a migration guide.

DeprecationPermalink to this section

Nothing is removed in the release that deprecates it. The gap is what makes an upgrade plannable rather than urgent.

Deprecate in a minor releaseThe old API keeps working and keeps being tested. It is marked with @deprecated, so editors surface it inline, and the changelog names the replacement.
Document the migrationEvery deprecation ships with a before-and-after example. A deprecation without a migration path is just a warning nobody can act on.
Warn in developmentA console warning fires once per deprecated API, in development only. It never appears in production builds.
Remove in the next majorAt minimum one minor release later, and usually several. The removal is listed in the migration guide with the codemod that handles it.

src/components/ui/example.tsx

export interface ExampleProps {
  /**
   * @deprecated Use `tone` instead. Removed in 3.0.
   * The old name described the colour rather than the meaning.
   */
  color?: "purple" | "red";

  tone?: "brand" | "danger";
}

// Both work during the deprecation window; the old one
// warns once, in development only.
if (process.env.NODE_ENV !== "production" && color) {
  warnOnce("Example: `color` is deprecated. Use `tone`.");
}

From merge to publishedPermalink to this section

What runs between a merged pull request and a version teams can install.

Lint and type-check on every pull request, with strict mode and no suppressions.
A production build, because a change that only fails at build time is the worst kind to find late.
Visual review of the documentation site, which renders every component in every state.
A manual keyboard pass over anything that changed an interactive component.
The version bump and changelog entry, written by the author and reviewed with the change.
Publish to the registry, with the documentation site deploying from the same commit.
An announcement naming every changed component and token, so consumers can decide whether to upgrade now.

UpgradingPermalink to this section

What a consuming team should do when a release lands.

Terminal

# Patch and minor releases are safe to take directly.
npm install @borneo/react@latest

# Major releases: read the migration guide first, then run
# the codemod, then review what it changed.
npx @borneo/codemod v3-migration src/
git diff

Codemods are a starting point

A codemod handles the mechanical renames. It cannot judge whether a component you were overriding still needs the override, so review the diff rather than committing it unread.

Support windowPermalink to this section

How long an old major keeps receiving fixes.

Version	Status	Receives
2.x	Current	Features, fixes and security patches
1.x	Maintenance	Security patches only, until six months after 3.0 ships
0.x	End of life	Nothing. Upgrade paths are documented but unsupported