> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Versioning

> How Catalyst uses branches, Git tags, and semantic versioning, and how to keep your project up to date with catalyst upgrade.

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](https://github.com/bigcommerce/catalyst/releases) and the [changelog](https://github.com/bigcommerce/catalyst/blob/canary/core/CHANGELOG.md) 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](#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](/developer/docs/storefront/catalyst/experiments/b2b-edition) beta program.

You can also find a list of all [Catalyst release tags](https://github.com/bigcommerce/catalyst/tags) in the Catalyst repository.

## How we handle versioning

Catalyst uses [semantic versioning (SemVer)](https://semver.org/).

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`](/developer/docs/storefront/catalyst/getting-started/upgrading) 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.