Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (94 loc) · 7.45 KB

CONTRIBUTING.md

File metadata and controls

149 lines (94 loc) · 7.45 KB

Contributing to Catalyst

Thanks for showing interest in contributing!

The following is a set of guidelines for contributing to Catalyst. These are just guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Repository Structure

Catalyst is a monorepo that contains the code for the Catalyst Next.js application inside of core/, and supporting packages such as the GraphQL API client and the create-catalyst CLI in packages/.

The default branch for this repository is called canary. This is the primary development branch where active development takes place, including the introduction of new features, bug fixes, and other changes before they are released in stable versions.

To contribute to the canary branch, you can create a new branch off of canary and submit a PR against that branch.

API Scope

Catalyst is intended to work with the BigCommerce Storefront GraphQL API and not directly integrate out of the box with the REST Management API.

You're welcome to integrate the REST Management API in your own fork, but we will not accept pull requests that incorporate or depend on the REST Management API. If your contribution requires Management API functionality, it is out of scope for this project.

Makeswift Integration

In addition to canary, we also maintain the integrations/makeswift branch, which contains additional code required to integrate with Makeswift.

To contribute to the integrations/makeswift branch, you can create a new branch off of integrations/makeswift and submit a PR against that branch.

Keeping integrations/makeswift in sync with canary

Except for the additional code required to integrate with Makeswift, the integrations/makeswift branch is a mirror of the canary branch. This means that the integrations/makeswift branch should be kept in sync with the canary branch as much as possible.

Prerequisites

In order to complete the following steps, you will need to have met the following prerequisites:

Steps

  1. Fetch latest from origin

    git fetch origin

  2. Create a branch to perform a merge from canary

    git checkout -B sync-integrations-makeswift origin/integrations/makeswift

Tip

The -B flag means "create branch or reset existing branch":

  • If the local branch doesn't exist, it creates it from origin/integrations/makeswift
  • If the local branch exists, it resets it to match origin/integrations/makeswift

  1. Merge canary and resolve merge conflicts, if necessary:

    git merge canary

Warning

Gotchas when merging canary into integrations/makeswift:

  • The name field in core/package.json should remain @bigcommerce/catalyst-makeswift
  • The version field in core/package.json should remain whatever the latest published @bigcommerce/catalyst-makeswift version was
  • The latest release in core/CHANGELOG.md should remain whatever the latest published @bigcommerce/catalyst-makeswift version was

  1. After resolving any merge conflicts, open a new PR in GitHub to merge your sync-integrations-makeswift into integrations/makeswift. This PR should be code reviewed and approved before the next steps.

  2. Rebase integrations/makeswift to establish new merge base

    git checkout -B integrations/makeswift origin/integrations/makeswift
git rebase sync-integrations-makeswift

  3. Push the changes up to GitHub:

    git push origin integrations/makeswift

This should close the PR in GitHub automatically.

Important

Do not squash or rebase-and-merge PRs into integrations/makeswift. Always use a true merge commit or rebase locally (as shown below). This is to preserve the merge commit and establish a new merge base between canary and integrations/makeswift.

Cutting New Releases

Catalyst uses Changesets to manage version bumps, changelogs, and publishing. Releases happen in two stages:

  1. Cut a release from canary
  2. Sync that release into integrations/makeswift and cut again

This ensures integrations/makeswift remains a faithful mirror of canary while including its additional integration code.

Stage 1: Cut a release from canary

  1. Begin the release process by merging the Version Packages (canary) PR. When .changeset/ files exist on canary, a GitHub Action opens a Version Packages (canary) PR. This PR consolidates pending changesets, bumps versions, and updates changelogs. Merging this PR should publish new tags to GitHub, and optionally publish new package versions to NPM.

Stage 2: Sync and Release integrations/makeswift

  1. Follow steps 1-6 under "Keeping integrations/makeswift in sync with canary", with one addition: include a changeset for @bigcommerce/catalyst-makeswift in the sync merge commit rather than opening a separate PR for it afterwards.

    • Match the bump type from Stage 1 (e.g., if @bigcommerce/catalyst-core went from 1.4.2 to 1.5.0, use minor)

    • Create a changeset file in .changeset/ (e.g., .changeset/sync-canary-1-5-0.md):

      ---
"@bigcommerce/catalyst-makeswift": minor
---

Pulls in changes from the `@bigcommerce/catalyst-core@1.5.0` release. For more information, see the [changelog entry](https://github.com/bigcommerce/catalyst/blob/<canary-sha>/core/CHANGELOG.md#150).

    • Replace <canary-sha> with the merge commit SHA of the Version Packages PR on canary so the link remains stable

    • Amend this changeset into the merge commit alongside any other sync changes (changeset cleanup, core/package.json and core/CHANGELOG.md fixes, etc.)

  2. Merge the Version Packages (integrations/makeswift) PR: After the sync lands, Changesets will open a PR (similar to Stage 1) bumping @bigcommerce/catalyst-makeswift. Merge it following the same process. This cuts a new release of the Makeswift variant.

  3. Tags and Releases: Confirm tags exist for both @bigcommerce/catalyst-core and @bigcommerce/catalyst-makeswift. Update latest tags to point to the new releases:

    git fetch origin --tags
git tag @bigcommerce/catalyst-core@latest @bigcommerce/catalyst-core@<version> -f
git tag @bigcommerce/catalyst-makeswift@latest @bigcommerce/catalyst-makeswift@<version> -f
git push origin @bigcommerce/catalyst-core@latest -f
git push origin @bigcommerce/catalyst-makeswift@latest -f

Additional Notes

  • Release cadence: Teams typically review on Wednesdays whether to cut a release, but you may cut releases more frequently as needed.

Other Ways to Contribute

  • Consider reporting bugs, contributing to test coverage, or helping spread the word about Catalyst.

Git Commit Messages

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference pull requests and external links liberally

Thank you again for your interest in contributing to Catalyst!