How to contribute

This section describes how to actually work on facebook/react: branching, testing, debugging, and the conventions you should follow when changing code.

The official, user-facing contributing guide is at https://legacy.reactjs.org/docs/how-to-contribute.html. This page is the in-repo, engineer-focused complement to it.

Where to start

For most contributors:

1. Read overview/index and overview/architecture to know which package owns the thing you want to change.
2. Read the package's own README in packages/<name>/README.md if one exists.
3. Open an issue or comment on an existing one before writing anything beyond a small bug fix. The team prefers a short design discussion to a surprise PR for non-trivial changes.
4. Pick a branch from main and follow development-workflow.
5. Run testing locally before pushing.

What's in scope

The runtime is generally not the right place to add API surface. The team's bar for new public APIs is high and they typically incubate in the experimental release channel for many months before shipping to stable. If you have a feature idea, the better path is usually:

• An RFC for major API changes.
• A discussion issue here for smaller changes.

What is well-suited for a PR:

• Bug fixes (with a regression test, ideally written against react-noop-renderer).
• Internal refactors that don't touch published behavior.
• Documentation fixes — but note: most user-facing docs live at https://github.com/reactjs/react.dev, not here.
• Performance improvements with reproducible benchmarks.
• New compiler passes / lint rules in the compiler/ workspace.

What is generally out of scope here:

• New top-level APIs (use an RFC).
• New examples for react.dev (use the docs repo).
• Changes only to TypeScript typings (those live in DefinitelyTyped, not here — React itself is Flow-typed).

Working with feature flags

Almost everything new lands behind a flag in packages/shared/ReactFeatureFlags.js (or in one of the per-channel forks under packages/shared/forks/). The expected lifecycle of a flag:

1. Add the flag in ReactFeatureFlags.js. Default it to false.
2. Gate the new code on the flag.
3. Write tests that cover both the flag-on and flag-off branches. The Jest harness in scripts/jest/setupTests.js exposes gate and @gate test pragmas to do this.
4. Flip the flag in the experimental channel by setting it to true in packages/shared/forks/ReactFeatureFlags.js (the experimental fork) and/or the www-modern fork.
5. Bake for at least a few prereleases, ideally a few weekly cycles.
6. Flip in stable by changing the default in ReactFeatureFlags.js.
7. Delete the flag and the dead branch once it has been on in stable long enough.

See reference/configuration for the full channel/flag taxonomy.

PR expectations

The .github/PULL_REQUEST_TEMPLATE.md asks for:

• A short summary of the change.
• A test plan (what you ran, what passed).
• For bug fixes: a regression test in the same PR.
• For new behavior: at least one test exercising it.

CI (.github/workflows/runtime_build_and_test.yml) runs an extensive matrix of jobs on every PR — lint, multiple test channels (stable, experimental, www-modern, www-classic), the Flow type check, the lint-build verifier, the bundle-size diff via dangerfile.js, and the DevTools regression suite when DevTools files changed. Most PRs need to be green on all of those before merge.

For PRs from members of MAINTAINERS, a label is auto-applied by .github/workflows/shared_label_core_team_prs.yml. PRs from outside contributors get extra triage.

Sub-pages

• development-workflow — branches, commits, PR mechanics, release channels.
• testing — Jest, gates, test renderers, snapshot rules.
• debugging — how to inspect the fiber tree, log effects, set breakpoints in the work loop.
• patterns-and-conventions — code style, error handling, internal-import rules.
• tooling — Rollup, Flow, ESLint, the error-codes script, the prerelease automation.