Versioning

This page is for Developer.

Catalyst follows a structured versioning approach to distinguish between stable releases and ongoing development.

To stay updated on our releases, check out the Catalyst releases page and the changelog on GitHub.

How we use branches

The canary branch is the default branch for the Catalyst repository and contains the latest code in development. The most recent commit in canary may not be stable. The main branch is deprecated; use canary instead.

For the most recent stable code, refer to How we use tags below.

How we use tags

We create GitHub Releases from Git tags to indicate distributable releases of Catalyst. To get the latest stable release of Catalyst, you can use the following tags:

• Catalyst - @bigcommerce/catalyst-core@latest
• Catalyst (with Makeswift) - @bigcommerce/catalyst-makeswift@latest
• Catalyst (with Makeswift and the B2B Buyer Portal) - @bigcommerce/catalyst-b2b-makeswift@latest. This variant is part of the B2B Edition beta program.

You can also find a list of all Catalyst release tags in the Catalyst repository.

How we handle versioning

Catalyst uses semantic versioning (SemVer).

Each release includes a changeset that describes its changes and categorizes them as patch, minor, or major. Backwards-incompatible changes get a major version bump. Because “backwards incompatible” can mean different things in a customizable product, release notes call out updates that need extra effort to integrate.

These breaking or major changes include:

• Updates that affect the shopper experience.
• Modifications to the theme interface.
• Significant internal refactors that, while not altering functionality, create substantial merge conflicts when updating Catalyst.

Minor changes include:

• Adding new functionality that does not interfere with existing features.
• UI adjustments that do not modify prop interfaces.

Patch changes include:

• Small patches and bug fixes.

Update your project

To bring your project forward to a newer release, use the catalyst upgrade CLI command. It merges the target version into your project and leaves any conflicts with your customizations as standard Git conflict markers for you to resolve.

The more you customize Catalyst, the more conflicts an upgrade is likely to surface. To help you reason about them, each release’s changes include a migration guide when relevant, in the .changeset/*.md file for the change and in the description of the pull request that introduced it.