React is one of Facebook’s first open source projects that is both under very active development and is also being used to ship code to everybody onfacebook.com. We’re still working out the kinks to make contributing to this project as easy and transparent as possible, but we’re not quite there yet. Hopefully this document makes the process for contributing clear and answers some questions that you may have.

Code of Conduct

Facebook has adopted theContributor Covenant as its Code of Conduct, and we expect project participants to adhere to it. Please readthe full text so that you can understand what actions will and will not be tolerated.

Open Development

All work on React happens directly onGitHub. Both core team members and external contributors send pull requests which go through the same review process.

Semantic Versioning

React followssemantic versioning. We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes. When we make breaking changes, we also introduce deprecation warnings in a minor version so that our users learn about the upcoming changes and migrate their code in advance. Learn more about our commitment to stability and incremental migration inour versioning policy.

Every significant change is documented in thechangelog file.

Branch Organization

Submit all changes directly to themain branch. We don’t use separate branches for development or for upcoming releases. We do our best to keepmain in good shape, with all tests passing.

Code that lands inmain must be compatible with the latest stable release. It may contain additional features, but no breaking changes. We should be able to release a new minor version from the tip ofmain at any time.

Feature Flags

To keep themain branch in a releasable state, breaking changes and experimental features must be gated behind a feature flag.

Feature flags are defined inpackages/shared/ReactFeatureFlags.js. Some builds of React may enable different sets of feature flags; for example, the React Native build may be configured differently than React DOM. These flags are found inpackages/shared/forks. Feature flags are statically typed by Flow, so you can runyarn flow to confirm that you’ve updated all the necessary files.

React’s build system will strip out disabled feature branches before publishing. A continuous integration job runs on every commit to check for changes in bundle size. You can use the change in size as a signal that a feature was gated correctly.

Bugs

Where to Find Known Issues

We are usingGitHub Issues for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn’t already exist.

Reporting New Issues

The best way to get your bug fixed is to provide a reduced test case. ThisJSFiddle template is a great starting point.

Security Bugs

Facebook has abounty program for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.

How to Get in Touch

• IRC:#reactjs on freenode
• Discussion forums

There is alsoan active community of React users on the Discord chat platform in case you need help with React.

Proposing a Change

If you intend to change the public API, or make any non-trivial changes to the implementation, we recommendfiling an issue. This lets us reach an agreement on your proposal before you put significant effort into it.

If you’re only fixing a bug, it’s fine to submit a pull request right away but we still recommend to 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:

How to Contribute to an Open Source Project on GitHub

To help you get your feet wet and get you familiar with our contribution process, we have a list ofgood first issues that contain bugs that have a relatively limited scope. This is a great place to get started.

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don’t accidentally duplicate your effort.

If somebody claims an issue but doesn’t follow up for more than two weeks, it’s fine to take it over but you should still leave a comment.

Sending a Pull Request

The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. For API changes we may need to fix our internal uses at Facebook.com, which could cause some delay. We’ll do our best to provide updates and feedback throughout the process.

Before submitting a pull request, please make sure the following is done:

1. Forkthe repository and create your branch frommain.
2. Runyarn in the repository root.
3. If you’ve fixed a bug or added code that should be tested, add tests!
4. Ensure the test suite passes (yarn test). Tip:yarn test --watch TestName is helpful in development.
5. Runyarn test --prod to test in the production environment.
6. If you need a debugger, runyarn test --debug --watch TestName, openchrome://inspect, and press “Inspect”.
7. Format your code withprettier (yarn prettier).
8. Make sure your code lints (yarn lint). Tip:yarn linc to only check changed files.
9. Run theFlow typechecks (yarn flow).
10. If you haven’t already, complete the CLA.

Contributor License Agreement (CLA)

In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you’ve done this for another Facebook open source project, you’re good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username.

Complete your CLA here.

Contribution Prerequisites

• You haveNode installed at LTS andYarn at v1.2.0+.
• You haveJDK installed.
• You havegcc installed or are comfortable installing a compiler if needed. Some of our dependencies may require a compilation step. On OS X, the Xcode Command Line Tools will cover this. On Ubuntu,apt-get install build-essential will install the required packages. Similar commands should work on other Linux distros. Windows will require some additional steps, see thenode-gyp installation instructions for details.
• You are familiar with Git.

Development Workflow

After cloning React, runyarn to fetch its dependencies.Then, you can run several commands:

• yarn lint checks the code style.
• yarn linc is likeyarn lint but faster because it only checks files that differ in your branch.
• yarn test runs the complete test suite.
• yarn test --watch runs an interactive test watcher.
• yarn test --prod runs tests in the production environment.
• yarn test <pattern> runs tests with matching filenames.
• yarn debug-test is just likeyarn test but with a debugger. Openchrome://inspect and press “Inspect”.
• yarn flow runs theFlow typechecks.
• yarn build creates abuild folder with all the packages.
• yarn build react/index,react-dom/index --type=UMD creates UMD builds of just React and ReactDOM.

We recommend runningyarn test (or its variations above) to make sure you don’t introduce any regressions as you work on your change. However, it can be handy to try your build of React in a real project.

First, runyarn build. This will produce pre-built bundles inbuild folder, as well as prepare npm packages insidebuild/packages.

The easiest way to try your changes is to runyarn build react/index,react-dom/index --type=UMD and then openfixtures/packaging/babel-standalone/dev.html. This file already usesreact.development.js from thebuild folder so it will pick up your changes.

If you want to try your changes in your existing React project, you may copybuild/node_modules/react/umd/react.development.js,build/node_modules/react-dom/umd/react-dom.development.js, or any other build products into your app and use them instead of the stable version.

If your project uses React from npm, you may deletereact andreact-dom in its dependencies and useyarn link to point them to your localbuild folder. Note thatinstead of--type=UMD you’ll want to pass--type=NODE when building. You’ll also need to build thescheduler package:

cd ~/path_to_your_react_clone/yarn build react/index,react/jsx,react-dom/index,scheduler--type=NODEcd build/node_modules/reactyarnlinkcd build/node_modules/react-domyarnlinkcd ~/path/to/your/projectyarnlink react react-dom

Every time you runyarn build in the React folder, the updated versions will appear in your project’snode_modules. You can then rebuild your project to try your changes.

If some package is still missing (e.g. maybe you usereact-dom/server in your project), you can always do a full build withyarn build. Note that runningyarn build without options takes a long time.

We still require that your pull request contains unit tests for any new functionality. This way we can ensure that we don’t break your code in the future.

Style Guide

We use an automatic code formatter calledPrettier.Runyarn prettier after making any changes to the code.

Then, our linter will catch most issues that may exist in your code.You can check the status of your code styling by simply runningyarn linc.

However, there are still some styles that the linter cannot pick up. If you are unsure about something, looking atAirbnb’s Style Guide will guide you in the right direction.

Request for Comments (RFC)

Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are “substantial”, and we ask that these be put through a bit of a design process and produce a consensus among the React core team.

The “RFC” (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project. You can contribute by visiting therfcs repository.

License

By contributing to React, you agree that your contributions will be licensed under its MIT license.

What Next?

Read thenext section to learn how the codebase is organized.