How to contribute
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.
Code of conduct
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 React follows 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.
We tag every pull request with a label marking whether the change should go in the next patch, minor, or a major version. We release new patch versions most weeks, minor versions every couple weeks, and major versions one or two times a year.
Every significant change is documented in the CHANGELOG. We have a Probot
We do our best to keep
master releasable at all times, with work for major releases happening in separate branches. Breaking changes should never be merged directly to
master. Otherwise, if you send a pull request please do it against the
master branch. Continue reading for more about pull requests and breaking changes.
Where to find known issues
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, where someone has commented within the last two weeks they are working on it, or the issue is labeled with fix in progress. We will do our best to communicate when an issue is being worked on internally.
Reporting new issues
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
Otherwise, request a feature.
How to get in touch
Proposing a change
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.
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.
Your first pull request
Working on your first pull request? You can learn how from this free video series:
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.
Sending a pull request
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
yarnin the repository root
- If you’ve fixed a bug or added code that should be tested, add tests
- Ensure the test suite passes with
yarn test:watch TestNameis helpful in development)
- If your pull request modifies any SVG files run
- Format your code with
- Make sure your code lints with
- Run the TypeScript compiler with
🎩your changes locally with
- If you haven’t already, sign a CLA
Contributor License Agreement (CLA)
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 v10.13.0+ and Yarn at v1.10.1+
After cloning Polaris React, run
yarn to fetch its dependencies. Then you can run several commands:
yarn devruns a Storybook server which includes a playground editable at
yarn testruns the complete test suite
yarn test:coverageruns tests and generates a test coverage report
yarn test <pattern>runs tests with matching filenames
yarn tophatruns a local development server and mounts all of the component examples
We recommend running
yarn test (or its variations above), as well as trying your build of Polaris React in a real project, to make sure you don’t introduce any regressions as you work on your change.
yarn run build-consumer <project> where
<project> is the directory the build will be copied. The
<project> directory must be a sibling of the
# Example yarn run build-consumer polaris-styleguide
In the example above, the build is copied to
polaris-styleguide/node_modules/@shopify/polaris. And in this case, a rebuild of
polaris-styleguide is required after copying the
polaris-react build, but may not be the case for all consuming projects.
We use an automatic code formatter called Prettier. Run
yarn 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
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.
If your pull request contains breaking changes, please target the branch for the next major release and open a pull request against
master 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
master 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.