Fixed Versioning

Fixed versioning maintains the same version number across all packages in a design system monorepo. When any package changes, all packages receive the same version bump. This approach simplifies compatibility understanding and consumer experience at the cost of increased version churn.

What Is Fixed Versioning

Fixed versioning is a monorepo versioning strategy where all packages share a single version number. If the design system is at version 5.0.0, all packages (@design-system/components, @design-system/tokens, @design-system/utils) are at version 5.0.0. A change to any package bumps all packages to the new version.

This approach treats the entire design system as a cohesive unit. Consumers know that any packages at version 5.0.0 are designed to work together. The version number represents the design system as a whole rather than individual packages.

How Fixed Versioning Works

Fixed versioning requires coordinated version bumps across all packages and clear rules about what triggers each bump type. Tooling automates the coordination.

Version determination considers changes across all packages. If any package has a breaking change, all packages receive a major bump. If any package has a new feature (no breaking changes), all packages receive a minor bump. Only if all changes are fixes do packages receive a patch bump.

Coordination applies the same version everywhere. Tooling like Lerna in fixed mode updates all package.json files to the new version. Changelogs indicate which packages actually changed while all reflect the new version.

Publishing releases all packages together. Even packages without changes receive new versions and are republished. This ensures all packages at the same version are available simultaneously.

Key Considerations

• Version inflation affects packages without changes
• Consumer compatibility is simplified
• Changelog clarity requires noting which packages actually changed
• Storage increases from republishing unchanged packages
• All packages must be ready to release together

Common Questions

Does fixed versioning waste version numbers?

Fixed versioning does cause version inflation for unchanged packages. A package might go from version 5.0.0 to 6.0.0 without any changes to its code. This raises legitimate questions about whether version numbers remain meaningful.

From the individual package perspective, version numbers lose precision. A consumer cannot determine from version alone whether a specific package changed.

From the system perspective, version numbers gain meaning. The version represents the design system state. All packages at version 6.0.0 reflect the design system at a consistent point in time.

The tradeoff is appropriate when packages are tightly coupled and typically used together. When consumers generally install multiple packages and expect them to work together, fixed versioning simplifies their experience despite version inflation.

How do changelogs work with fixed versioning?

Changelogs require adaptation for fixed versioning since not all packages change in each release. Several approaches address this.

Consolidated changelogs list changes by package within each version entry. The version 6.0.0 entry shows which packages changed and what changed in each. Unchanged packages may be omitted or noted as unchanged.

Per-package changelogs still exist and note when packages were released without changes. An entry might read “Released with design system version 6.0.0. No changes to this package.” This maintains per-package history while acknowledging the fixed versioning context.

System-level changelogs focus on the design system as a whole. Instead of tracking individual package changes, these changelogs describe design system evolution. This approach aligns with treating the system as a cohesive unit.

The best approach depends on consumer needs. Consumers wanting to understand specific package changes benefit from detailed per-package information. Consumers treating the design system as a unit may prefer system-level summaries.

Summary

Fixed versioning maintains the same version across all design system packages, simplifying compatibility understanding. Changes to any package trigger version bumps for all packages. This approach trades version precision for simplicity, suiting tightly coupled package collections used together.