Skip to content

Fix factual discrepancies in Catalyst documentation #1063

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fix factual discrepancies in Catalyst documentation #1063

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f864339
Initial plan
Copilot Aug 24, 2025
dafb253
Fix factual discrepancies in Catalyst documentation
Copilot Aug 24, 2025
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
13 changes: 6 additions & 7 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 @@ -15,14 +15,13 @@ For the most recent stable code, refer to [How we use tags](#how-we-use-tags) be
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`
- Catalyst (with Makeswift) - `@bigcommerce/catalyst-makeswift@latest`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [remark-lint] reported by reviewdog 🐶
Makeswift is misspelt; did you mean Makeshift? retext-spell retext-spell


<Callout type="warning">
Until version 1.0 of Catalyst is released, the release deployed using
[One-Click Catalyst](/docs/storefront/catalyst/getting-started/workflows/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.
<Callout type="info">
As of Catalyst v1.0.0 release, the release deployed using
[One-Click Catalyst](/docs/storefront/catalyst/getting-started/workflows/one-click-catalyst) uses the
stable `@bigcommerce/catalyst-makeswift@latest` tag. For development and
testing purposes, canary releases are available via the `@bigcommerce/catalyst-makeswift@canary` tag.
</Callout>

You can also find a list of all [Catalyst release tags](https://github.com/bigcommerce/catalyst/tags) in the Catalyst repository.
Expand Down
10 changes: 5 additions & 5 deletions docs/storefront/catalyst/getting-started/workflows/integrate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,20 @@ Now, you can begin to write the code required to make your integration work!

There are a handful of lessons we have learned from building integrations into Catalyst ourselves; we wanted to offer those lessons as tips to follow while building your own integration. You should highly consider incorporating these tips into your own workflow, as we have found it has saved us time and headache.

1. Keep your integration code as maintainable as possible. You'll notice that the [`integrations/makeswift` branch](https://github.com/bigcommerce/catalyst/compare/main...integrations/makeswift) has only a single commit, and about 20 changed files. This means that merge conflicts caused rebasing on top of the latest `upstream/main` to update your integration are easier to deal with.
2. Explicitly call out when your integration makes use of newly introduced environment variables. You'll notice that the [`integrations/makeswift` branch](https://github.com/bigcommerce/catalyst/compare/main...integrations/makeswift) adds a new environment variable called `MAKESWIFT_SITE_API_KEY`; by explicitly listing newly introduced environment variables in a version-controlled file like `.env.example`, it makes it obvious to the consumers of your integration when they need to add new environment variables to make your integration work.
1. Keep your integration code as maintainable as possible. You'll notice that the [`integrations/makeswift` branch](https://github.com/bigcommerce/catalyst/compare/canary...integrations/makeswift) has only a single commit, and about 20 changed files. This means that merge conflicts caused rebasing on top of the latest `upstream/canary` to update your integration are easier to deal with.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [remark-lint] reported by reviewdog 🐶
rebasing is misspelt; did you mean debasing, rebating? retext-spell retext-spell

2. Explicitly call out when your integration makes use of newly introduced environment variables. You'll notice that the [`integrations/makeswift` branch](https://github.com/bigcommerce/catalyst/compare/canary...integrations/makeswift) adds a new environment variable called `MAKESWIFT_SITE_API_KEY`; by explicitly listing newly introduced environment variables in a version-controlled file like `.env.example`, it makes it obvious to the consumers of your integration when they need to add new environment variables to make your integration work.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [remark-lint] reported by reviewdog 🐶
Hard to read sentence (confidence: 5/7) retext-readability retext-readability


### Open a PR to add your integration to upstream

Now that your branch is ready for public use, please start by opening a new issue in the Catalyst upstream GitHub repository. In your issue, request the creation of an `integrations/<INTEGRATION_NAME>` branch. Once the branch is created, you can target it with your pull request to contribute your integration code back upstream.

### Keeping your integration up to date

Keeping your integration up to date is as simple as rebasing your integration branch on top of the latest changes introduced to `upstream/main`, and then opening a PR from your origin remote fork integration branch into the integration branch with the same name on the upstream remote repository.
Keeping your integration up to date is as simple as rebasing your integration branch on top of the latest changes introduced to `upstream/canary`, and then opening a PR from your origin remote fork integration branch into the integration branch with the same name on the upstream remote repository.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [remark-lint] reported by reviewdog 🐶
Hard to read sentence (confidence: 4/7) retext-readability retext-readability

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [remark-lint] reported by reviewdog 🐶
rebasing is misspelt; did you mean debasing, rebating? retext-spell retext-spell


```shell copy
git checkout integrations/<INTEGRATION_NAME>
git fetch upstream main
git pull --rebase upstream main
git fetch upstream canary
git pull --rebase upstream canary
git push --force-with-lease origin integrations/<INTEGRATION_NAME>
```