Polaris React is Shopify’s most active open source project. It’s the only project that’s both under very active development and is used to build Shopify and Shopify apps every day. We want to make it as easy and transparent as possible to contribute. If we are missing anything or can make the process easier in any way, please let us know.
We expect all participants to read our code of conduct to understand which actions are and aren’t tolerated.
All work on Polaris React happens directly on GitHub. Both team members and external contributors send pull requests which go through the same review process.
Polaris packages follow semantic versioning. We release patch versions for bug fixes, minor versions for new features, and major versions for breaking changes. When we make breaking changes, we introduce deprecation warnings in a minor version along with the upgrade path so that our users learn about the upcoming changes and migrate their code in advance.
The following sections detail what kinds of changes result in each of major, minor, and patch version bumps:
- Removal of a component
- Removal of a prop from a component
- Change to the type accepted for a prop
- Breaking changes to minimum version of dependencies
- Breaking changes to public Sass variables, functions and mixins
- New component
- New prop for a component
- Additional type accepted for a prop
- Deprecation of a component, prop, public Sass variable, function, or mixin (ahead of its removal in the next major version)
- Breaking change to the HTML generated by a component, including addition, removal, or renaming of classes
- Changes that do not impact public APIs
- Non-breaking changes to minimum version of dependencies
- Breaking changes to private Sass variables, functions, and mixins
We do our best to keep main releasable at all times, with work for major releases happening in separate branches. Breaking changes should never be merged directly to main. Otherwise, if you send a pull request please do it against the main branch. Continue reading for more about pull requests and breaking changes.
We track all of our issues in GitHub and bugs are labeled accordingly. If you are planning to work on an issue, avoid ones which already have an assignee or where someone has commented within the last two weeks they are working on it. We will do our best to communicate when an issue is being worked on internally.
To reduce duplicates, look through open issues before filing one. When opening an issue, complete as much of the template as possible. The best way to get your bug fixed is to provide a reduced test case. This CodeSandbox template is a great starting point.
Before requesting a feature, search the existing feature requests. You can 👍 upvote feature requests to help the Polaris team set priorities. If a feature request is closed, you can still upvote! A closed feature request means it’s not something we’re currently working on, but we take all your input into account when planning what to work on next.
Otherwise, request a feature.
If you intend to build a new component, change a public API, make design improvements, or any other non-trivial changes, we recommend filing an issue. This lets us all discuss and reach an agreement on the proposal before you put in significant time and effort.
Please use this template for proposing new components or changes to existing components.
If you’re only fixing a bug, it’s okay to submit a pull request right away but we still recommend you file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue.
Working on your first pull request? You can learn how from this free video series:
How to Contribute to an Open Source Project on GitHub
To help you get familiar with our contribution process, we have a list of good first issues that contain bugs with limited scope. This is a great place to get started.
If you decide to fix an issue, please check the comment thread in case somebody is already working on a fix. If nobody is working on it, leave a comment stating that you intend to work on it.
If somebody claims an issue but doesn’t follow up for more than two weeks, it’s fine to take it over but still leave a comment stating that you intend to work on it.
We’ll review your pull request and either merge it, request changes to it, or close it with an explanation. We’ll do our best to provide updates and feedback throughout the process.
Before submitting a pull request, please:
- Fork the repository and create your branch from
main - Run
pnpmin the repository root - If you’ve fixed a bug or added code, make sure to add tests
- Ensure the test suite passes with
pnpm test(protip:pnpm test:watch TestNameis helpful in development) - Format your code with
pnpm format - Make sure your code lints with
pnpm lint - Run the TypeScript compiler with
pnpm type-check - Tophat 🎩 your changes locally in Storybook with
pnpm dev - Create a changeset by running
pnpm changeset. More info. - If you haven’t already, sign a CLA
The changelog is created with Changesets.
A changeset describes changes made in a branch or commit. It holds three bits of information:
- What packages we need to release
- What version we are releasing packages
- A changelog entry for the released packages
Add a changeset if you have made any changes that will require a package version bump and release:
- Run
pnpm changeset. - Select the packages you want to include using ↑ and ↓ to navigate to packages, and space to select a package. Hit enter when all desired packages are selected.
- Select a bump type for each selected package.
- Provide a message to be written into the changelog on the next release.
Keep the following in mind when authoring your changelog entry (final prompt after running pnpm changeset):
- Use a positive, conversational tone (for example, use “support” over “allow” and other authoritative verbs)
- Avoid redundancy when possible (try to phrase a bug fix entry without the word “bug”)
- Use sentence case
- Use plain language
Generally, changes related to these topics can be omitted:
- polaris.shopify.com
- Dev dependencies upgrades
- Chores (infrastructure, release process…)
Each contributor is required to sign a CLA. This process is automated as part of your first pull request and is only required once. If any contributor has not signed or does not have an associated GitHub account, the CLA check will fail and the pull request is unable to be merged.
- You have Node installed at v20.11.1+ and Pnpm at v8+
Use the documentation directory for guidance on: accessibility testing and adding to the changelog. For code style best practices, take a look at existing components.
Making sure the voice and tone is consistent across Polaris is important to us, for more information visit the voice and tone guidelines.
See the README.md file for documentation on the development workflow.
We recommend running tests as well as trying your build of a package in a real project, to make sure you don’t introduce any regressions as you work on your change.
pnpm testwill run tests for all packagespnpm turbo run test --filter="[HEAD^1]"will test any package that has changed in the last commit
You can test your changes in another project locally by creating a snapshot release.
On your feature branch PR, ensure you have a changeset indicating which package or packages to version. Then, create a new comment in your feature branch PR with the text "/snapit". This will kickoff a snapshot release to npm.
Once the snapshot is ready, there will be a new comment in your feature PR with the newly released versions. In your external project, add the snapshot package or packages. An example snapshot package should have the following format:
pnpm add @shopify/[email protected]Run the project as usual to tophat local changes. If you need to make updates, push new package changes to your feature PR and create a new snapshot release.
We use an automatic code formatter called Prettier. Run pnpm format after making any changes to the code.
Linting will catch common issues that may exist in your code. You can check the status of your code styling by running pnpm lint.
Our code editor of choice is VS Code which has integrations with Prettier and our linting tools which make this automatic. If you choose to use VS Code, these integrations will be listed as recommended extensions (or search for @recommended) in the extensions panel.
However, there are still some styles that the linter cannot pick up. If you are unsure about something, looking at our JavaScript and CSS guides may help.
If your pull request contains breaking changes, please target the next branch for the next major release. Also, open a pull request against main that introduces the deprecation warnings and upgrade path.
If you are unsure if the changes are considered breaking or not, open your pull request against the main branch and let us know. We understand it can be uncomfortable asking for help and this is why we have a code of conduct to ensure the community is positive, encouraging, and helpful.