CONTRIBUTING.md

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.

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:

• You have a remote named origin pointing to the bigcommerce/catalyst repository on GitHub. If you do not, you can add it with git remote add origin ssh://git@github.com/bigcommerce/catalyst.git, or if you are not using SSH, you can use git remote add origin https://github.com/bigcommerce/catalyst.git.
• You have rights to push to the integrations/makeswift branch on GitHub.

Steps

To pull the latest code from canary into integrations/makeswift, follow the steps below:

1. Ensure your local canary branch is synchronized with the remote canary branch:

   git fetch origin
   git checkout canary
   git reset --hard origin/canary

2. Fetch the latest code from integrations/makeswift:

   git checkout -B 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

3. Checkout a new branch from integrations/makeswift:

   git checkout -b {new-branch-name}

4. Merge canary into {new-branch-name}, and resolve merge conflicts, if necessary:

   git merge canary

Warning

There are a number of "gotchas" that you need to be aware of 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 .changeset/ directory should not include any files that reference the "@bigcommerce/catalyst-core" package. If these files are merged into integrations/makeswift, they will cause the Changesets Release GitHub Action in .github/workflows/changesets-release.yml to fail with the error: Error: Found changeset for package @bigcommerce/catalyst-core which is not in the workspace

Note: A GitHub Action is in place to help prevent invalid changesets from being merged into integrations/makeswift. Do not merge your PR if this GitHub Action fails.

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

6. Once your PR is approved, the next step is to incorporate the merge commit from {new-branch-name} into integrations/makeswift. Do not use the merge button in the GitHub UI to merge your PR. Instead, you'll want to run the following command locally:

   git checkout integrations/makeswift
   git rebase {new-branch-name}

Important

We have added a GitHub Ruleset to protect against this, but it's worth explicitly documenting here for posterity: It is very important that we do not "Squash and merge" or "Rebase and merge" our changes onto integrations/makeswift. Instead, we should either merge the PR with a traditional merge commit (the button in the GitHub PR UI should say "Merge pull request"), or locally rebase the integrations/makeswift branch onto the {new-branch-name} branch (as illustrated in the step above). Either of these options will correctly preserve the merge commit from step 4 in the history of the integrations/makeswift branch, which will then set the new merge base for future merges from canary into integrations/makeswift.

If you are unsure whether or not you've done this correctly, you can run git merge canary from integrations/makeswift after rebasing in the step above; if you see "Already up to date.", you followed the steps correctly (with one caveat: in the case that new commits have been pushed to canary since the last time you merged, then you may see a new merge commit/potential conflicts for only those new commits).

7. Push the changes up to GitHub, which will automatically close the open PR from step 5.

   git push origin integrations/makeswift

Cutting new releases

This repository uses Changesets to manage version bumps, changelogs, and publishing to the NPM registry. Whenever you create a pull request, you should think about whether the changes you are making warrant a version bump or a changelog entry.

If you are not sure, you can ask in the PR. Here are some examples:

• If your pull request introduces changes to the root README.md: Likely does not warrant a version bump or changelog entry, therefore your PR does not need to include a Changeset.
• If your pull request introduces changes to core/, e.g., core/app/, or any of the packages in packages/: Likely warrants a version bump and changelog entry, therefore your PR should include a Changeset.

You can run the following command to create a new version bump and changelog entry:

pnpm changeset

An interactive prompt will take you through the process of adding your changeset.

Once you've completed the interactive prompt, you'll see a new file in the .changeset/ directory. This file contains the version bump and changelog entry for your changes. You should commit this file to the branch associated with your PR.

Once your PR is merged, our GitHub Action will handle the process of versioning and updating the changelog, (and in the case of packages/, publishing your changes to NPM). No further action is needed from you.

Warning

It is very important that .changeset/*.md files targeting packages in packages/ are not merged into the integrations/makeswift branch. While it is technically feasible to release packages from integrations/makeswift, we never want to do this. If we did this, we would need to sync the branches in the opposite direction, which was never intended to happen.

Note: A GitHub Action is in place to help prevent invalid changesets from being merged into integrations/makeswift. Do not merge your PR if this GitHub Action fails.

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!