Fix factual discrepancies in Catalyst documentation #1063
Conversation
Co-authored-by: bookernath <[email protected]>
| @@ -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. | |||
There was a problem hiding this comment.
rebasing is misspelt; did you mean debasing, rebating? retext-spell retext-spell
| 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. | ||
| 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Hard to read sentence (confidence: 4/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. |
There was a problem hiding this comment.
rebasing is misspelt; did you mean debasing, rebating? retext-spell retext-spell
| @@ -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` | |||
There was a problem hiding this comment.
Makeswift is misspelt; did you mean Makeshift? retext-spell retext-spell
This PR addresses several factual inaccuracies in the Catalyst documentation that were outdated due to recent releases and changes in the repository structure.
Key Issues Fixed
Version 1.0.0 Release Status
The documentation incorrectly stated "Until version 1.0 of Catalyst is released" when v1.0.0 was actually released on June 16, 2025. Updated the One-Click Catalyst deployment information to reflect that stable releases are now available.
Tag Naming Conventions
Fixed incorrect tag references throughout the versioning documentation:
@bigcommerce/catalyst-core@makeswift-latestto@bigcommerce/catalyst-makeswift@latestBranch Structure Updates
Updated integration workflow documentation to reflect the correct default branch structure:
maintocanaryin integration examplescanaryas the base branchupstream/canaryinstead ofupstream/mainVerification Process
All changes were verified against:
These updates ensure the documentation accurately reflects the current state of Catalyst and provides correct guidance for developers using the framework.
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
https://api.github.com/repos/bigcommerce/catalystcurl -s REDACTED(http block)If you need me to access, download, or install something from one of these locations, you can either:
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.