Independent Versioning

Independent versioning allows each design system package to maintain its own version number, evolving at its own pace. Changes to one package do not automatically affect other packages’ versions. This approach suits design systems with loosely coupled packages that evolve at different rates.

What Is Independent Versioning

Independent versioning is a monorepo versioning strategy where each package has its own version. Package A might be at version 3.2.1 while Package B is at version 1.0.5. Versions change only when the specific package changes, not when sibling packages change.

This approach contrasts with fixed versioning where all packages share a single version number. Independent versioning provides more granular version information but requires more coordination to ensure compatibility between packages.

How Independent Versioning Works

Independent versioning requires tracking changes per package, bumping versions individually, and managing cross-package compatibility. Tooling helps manage this complexity.

Change tracking identifies which packages changed since their last release. Each package is evaluated independently. A package with no changes since its last release does not receive a version bump, even if other packages changed significantly.

Version bumping applies semantic versioning per package. Major, minor, and patch decisions are made for each changed package based on its specific changes. A breaking change in Package A triggers a major bump only for A.

Compatibility management ensures packages work together. When packages depend on each other, version ranges must be maintained correctly. If Package B depends on Package A, B’s dependency specification must work with both A’s current and potential future versions.

Release coordination publishes updated packages together or separately. Even with independent versions, related changes often release simultaneously. Tooling can coordinate publishing while maintaining independent version numbers.

Key Considerations

• Document compatibility between packages at different versions
• Maintain appropriate peer dependency ranges
• Consider consumer experience when packages interdepend
• Use tooling designed for independent versioning
• Communicate version changes clearly to consumers

Common Questions

How do consumers know which package versions work together?

Compatibility between independently versioned packages requires explicit documentation. Several approaches help consumers understand what works together.

Peer dependency specifications express compatibility. If @design-system/react version 2.3.0 specifies @design-system/tokens peer dependency as ^3.0.0, consumers know tokens versions 3.x.x should work with react 2.3.0.

Compatibility matrices document tested combinations. Documentation showing which package versions have been tested together helps consumers choose working combinations.

Release announcements highlight related packages. When packages release together, noting this in release communications helps consumers update related packages simultaneously.

Dependency management tools like Renovate or Dependabot can be configured to update related packages together, helping consumers maintain compatible combinations.

What challenges does independent versioning create?

Independent versioning introduces complexity that teams should understand before adopting.

Version tracking becomes more complex. Consumers using multiple packages must track multiple versions. Teams managing the monorepo must understand each package’s version history.

Compatibility testing expands. The number of possible version combinations grows with independent versioning. Testing all combinations is impractical; focusing on supported combinations is necessary.

Communication requires more detail. Release announcements must specify which packages changed. Consumers cannot assume all packages updated together.

Consumer confusion can arise. Seeing packages at different versions (one at v8, another at v2) may seem inconsistent. Clear explanation of why versions differ helps manage expectations.

Summary

Independent versioning allows design system packages to evolve separately with individual version numbers. This approach prevents unnecessary version inflation but requires careful compatibility management. Teams should document compatibility and use appropriate tooling to manage independent versioning complexity.