Skip to content

DEVDOCS-6672 - Add note that catalyst main branch is deprecated #1226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chris-nowicki merged 1 commit into from
Jan 7, 2026
Merged

DEVDOCS-6672 - Add note that catalyst main branch is deprecated #1226

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 19 additions & 14 deletions docs/storefront/catalyst/getting-started/versioning.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,14 @@ Catalyst follows a structured versioning approach to distinguish between stable

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.

<Callout type='warning'>
The `main` branch is deprecated. The `canary` branch is now the default branch
for the Catalyst repository and should be used instead of `main`.
</Callout>

## 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.
The `canary` branch contains the latest code in development and is the default branch for the Catalyst repository. Note that the most recent commit in `canary` may not be stable.

For the most recent stable code, refer to [How we use tags](#how-we-use-tags) below.

Expand Down Expand Up @@ -81,17 +86,17 @@ While the exact steps you need to follow vary widely depending on how you've con
git merge @bigcommerce/catalyst-makeswift@latest
```

<Callout type="warning">
If you originally created your Catalyst project based on the version of
Catalyst without Makeswift, you will need to merge the latest
`@bigcommerce/catalyst-core@latest` tag into your interim branch instead of
the `@bigcommerce/catalyst-makeswift@latest` tag.
<Callout type='warning'>
If you originally created your Catalyst project based on the version of
Catalyst without Makeswift, you will need to merge the latest
`@bigcommerce/catalyst-core@latest` tag into your interim branch instead of
the `@bigcommerce/catalyst-makeswift@latest` tag.
</Callout>

5. Resolve any merge conflicts that arise. After resolving any merge conflicts, open a new PR in GitHub to merge your `your-interim-sync-branch` into `your-primary-development-branch`. This PR should be code reviewed and approved by your team before the next steps.

6. Once your PR is approved, the next step is to incorporate the merge commit from `your-interim-sync-branch` into `your-primary-development-branch`. There are a few ways to do this, and the best approach for you will depend on your workflow. Here are a couple of options:

- **Option 1: Merge your interim branch into your primary development branch using the GitHub UI:** This is the recommended approach if you are not comfortable with using the command line.

- **Option 2: Rebase your primary development branch on top of your interim branch release:** This is the recommended approach if you are comfortable with using the command line, and want to keep your commit history clean.
Expand All @@ -101,13 +106,13 @@ While the exact steps you need to follow vary widely depending on how you've con
git rebase your-interim-sync-branch
```

<Callout type="info" emoji="ℹ️">
Regardless of which option you choose, your goal is to incorporate the merge
commit (the commit with two parent commits) from `your-interim-sync-branch`
into `your-primary-development-branch`. This has the effect of establishing a
new merge base for your primary development branch, so that the next time you
pull in updates from `upstream`, you will not have to resolve any merge
conflicts that you've already resolved in your interim branch.
<Callout type='info'>
Regardless of which option you choose, your goal is to incorporate the merge
commit (the commit with two parent commits) from `your-interim-sync-branch`
into `your-primary-development-branch`. This has the effect of establishing a
new merge base for your primary development branch, so that the next time you
pull in updates from `upstream`, you will not have to resolve any merge
conflicts that you've already resolved in your interim branch.
</Callout>

7. If you went with option 2 above, you have one more step to complete. Push your changes to the remote `your-primary-development-branch`, which will automatically close the PR you opened in step 5:
Expand Down