Versioning
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 (opens in a new tab) and the changelog (opens in a new tab) on GitHub.
How we use branches
The canary branch contains the latest code in development and is the default branch for the Catalyst repository instead of main. Note that the most recent commit in canary may not be stable.
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-core@makeswift-latest
Until version 1.0 of Catalyst is released, the release deployed using
One-Click Catalyst will be from the
@bigcommerce/catalyst-core@makeswift-canary tag and is not guranteed to be
stable. After 1.0 is released, this will move to use the
@bigcommerce/catalyst-core@makeswift-latest which will be stable.
You can also find a list of all Catalyst release tags (opens in a new tab) in the Catalyst repository.
How we handle versioning
Catalyst is moving from a ZeroVer (opens in a new tab) versioning strategy to SemVer (opens in a new tab).
Each release includes a changeset that outlines changes, categorizing them as patch, minor, or major changes based on SemVer (opens in a new tab) versioning. Backwards-incompatible changes will now be tagged with major version bumps. While the exact definition of "backwards incompatible" can vary in a customizable product, we'll aim to provide clear communication on updates that might require 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.
How to handle updates
To update your local code against the latest stable release from Catalyst, you can merge changes from the latest release into your branch:
git fetch --tags
git merge @bigcommerce/catalyst-core@latestAlternatively, you can rebase your branch against the latest release:
git fetch --tags
git rebase tags/@bigcommerce/catalyst-core@latest