Versioning and Migration Strategy

Versioning Is a Promise

When you publish a component library, the version number is a promise to your consumers. "If you upgrade from 2.3.0 to 2.4.0, nothing will break." That is the social contract of semantic versioning, and violating it destroys trust faster than almost anything else.

The tricky part for design systems: what counts as a "breaking change"? A renamed prop is obviously breaking. But what about changing the default border-radius from 6px to 8px? What about a component that was 40px tall and is now 44px? These are visual changes, not API changes, but they can absolutely break layouts.

What Constitutes a Breaking Change

Here is the definitive list for component libraries. If you do any of these, it is a major version bump:

Definitely Breaking (Major)

Not Breaking (Minor or Patch)

• Adding a new optional prop
• Adding a new component or export
• Adding a new variant to an existing component
• Fixing a bug (component was not doing what docs said)
• Improving accessibility without changing visual appearance
• Internal refactoring with no external behavior change

Changelog Generation with Changesets

Manually maintaining a changelog is error-prone. Changesets automates it by requiring developers to declare the impact of their changes at PR time.

npm install @changesets/cli
npx changeset init

When a developer makes a change, they run:

npx changeset

This prompts them to:

1. Select which packages changed
2. Classify the change as major, minor, or patch
3. Write a human-readable description

The result is a markdown file in .changeset/:

---
"@acme/ui": minor
---

Add `loading` prop to Button component. When `loading` is true, the button shows a spinner and is disabled.

When you are ready to release, run:

npx changeset version

This:

• Bumps version numbers in package.json
• Consolidates all changeset files into CHANGELOG.md
• Deletes the consumed changeset files

## 2.4.0

### Minor Changes

- Add `loading` prop to Button component. When `loading` is true, the button shows a spinner and is disabled.

Then publish:

npx changeset publish

CI Enforcement

# .github/workflows/changeset-check.yml
name: Changeset Check
on: pull_request

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm ci
      - run: npx changeset status --since=origin/main

The changeset status command fails if the PR includes publishable changes but no changeset file.

Migration Codemods with jscodeshift

When you do ship a breaking change (major version), help your consumers migrate. Codemods are automated code transformations that update consumer code to match the new API.

jscodeshift is the standard tool. It parses code into an AST, lets you find and replace patterns, and writes the transformed code back:

// codemod: rename variant="primary" to variant="default"
import type { API, FileInfo } from 'jscodeshift';

export default function transformer(file: FileInfo, api: API) {
  const j = api.jscodeshift;
  const root = j(file.source);

  root
    .findJSXElements('Button')
    .find(j.JSXAttribute, { name: { name: 'variant' } })
    .filter(path => {
      const value = path.node.value;
      return (
        value?.type === 'StringLiteral' && value.value === 'primary'
      );
    })
    .forEach(path => {
      if (path.node.value?.type === 'StringLiteral') {
        path.node.value.value = 'default';
      }
    });

  return root.toSource();
}

Consumers run:

npx jscodeshift -t ./codemods/rename-button-variant.ts ./src/**/*.tsx

Before:

<Button variant="primary">Submit</Button>

After:

<Button variant="default">Submit</Button>

Codemod for Prop Removal

// codemod: remove deprecated "outline" prop, add variant="outline" instead
export default function transformer(file: FileInfo, api: API) {
  const j = api.jscodeshift;
  const root = j(file.source);

  root
    .findJSXElements('Button')
    .forEach(path => {
      const attrs = path.node.openingElement.attributes;
      if (!attrs) return;

      const outlineIndex = attrs.findIndex(
        attr =>
          attr.type === 'JSXAttribute' &&
          attr.name.name === 'outline'
      );

      if (outlineIndex === -1) return;

      attrs.splice(outlineIndex, 1);

      const hasVariant = attrs.some(
        attr =>
          attr.type === 'JSXAttribute' &&
          attr.name.name === 'variant'
      );

      if (!hasVariant) {
        attrs.push(
          j.jsxAttribute(
            j.jsxIdentifier('variant'),
            j.stringLiteral('outline')
          )
        );
      }
    });

  return root.toSource();
}

Before:

<Button outline>Cancel</Button>

After:

<Button variant="outline">Cancel</Button>

The Deprecation Lifecycle

Never remove something without warning. The deprecation lifecycle gives consumers time to migrate:

Implementing Deprecation Warnings

interface ButtonProps {
  variant?: 'default' | 'destructive' | 'outline' | 'ghost';
  /** @deprecated Use `variant="outline"` instead. Will be removed in v3.0. */
  outline?: boolean;
}

function Button({ variant, outline, ...props }: ButtonProps) {
  if (process.env.NODE_ENV !== 'production' && outline !== undefined) {
    console.warn(
      '[ACME UI] Button: The "outline" prop is deprecated. ' +
      'Use variant="outline" instead. ' +
      'This prop will be removed in v3.0. ' +
      'Run `npx @acme/ui-codemods button-outline` to migrate automatically.'
    );
  }

  const resolvedVariant = outline ? 'outline' : (variant ?? 'default');

  return <button className={buttonVariants({ variant: resolvedVariant })} {...props} />;
}

The warning:

• Only fires in development (stripped from production builds)
• Says what is deprecated
• Says what to use instead
• Says when it will be removed
• Links to the automated migration tool

Gradual Adoption Strategy

Large organizations cannot upgrade all consumers simultaneously. Your versioning strategy must support gradual adoption.

Strategy 1: Side-by-Side Versions

Allow consumers to install two major versions simultaneously:

{
  "dependencies": {
    "@acme/ui": "^2.0.0",
    "@acme/ui-v3": "npm:@acme/ui@^3.0.0"
  }
}

import { Button } from '@acme/ui';           // v2
import { Button as ButtonV3 } from '@acme/ui-v3'; // v3

This works but doubles the bundle. Use it for gradual migration, not permanent coexistence.

Strategy 2: Feature Flags

Ship the new behavior behind a flag in a minor release:

import { DesignSystemProvider } from '@acme/ui';

<DesignSystemProvider features={{ newButtonSizing: true }}>
  <App />
</DesignSystemProvider>

Consumers opt in at their own pace. When the flag is stable, make it the default in the next major.