Contribute

Thanks for choosing to contribute! We look forward to improving web applications together. Here you will find information on how propose bug fixes, suggest improvements, and develop locally.

Better together#

We believe that the best way to build a better web is together as a community. The React Spectrum project aims to make it easier to build design systems and component libraries with high quality interactions and accessibility for all. The core team and all external contributors follow the same process in order maintain a high quality codebase.

Code of conduct#

We adhere to the Adobe code of conduct and by participating, you are expected to uphold this code. Please report unacceptable behavior to Grp-opensourceoffice@adobe.com.

Reporting issues#

Bugs#

We use GitHub issues to track work and log bugs. Please check existing issues before filing anything new. We do our best to respond to issues within a few days. If you would like to contribute a fix, please let us know by leaving a comment on the issue.

The best way to reduce back and forth on a bug is provide a small code example exhibiting the issue along with steps to reproduce it. If you would like to work on a bugfix yourself, make sure an issue exists first.

Please follow the issue templates when filing new ones and add as much information as possible.

Feature requests#

Our components can always be improved upon. If you have a feature request, you can use our Feature Request issue template. For larger scopes of work, it is a good idea to open a Request For Comments (RFC) first to gather feedback from the team. Please follow our RFC template. Make a PR to add your RFC to the rfcs folder to give the team and the community a chance to discuss the proposal.

Security issues#

Security issues shouldn't be reported on this issue tracker. Instead, please follow the directions here to contact our security team.

Pull Requests#

For significant changes, it is recommended that you first propose your solution in an RFC and gather feedback.

A few things to keep in mind before submitting a pull request:

  • Add a clear description covering your changes
  • Reference the issue in the description
  • Make sure linting and tests pass
  • Include relevant unit tests
  • Add/update stories in storybook for your changes
  • Update documentation
  • Remember that all submissions require review, please be patient.

The team will review all pull requests and do one of the following:

  • request changes to it (most common)
  • merge it
  • close it with an explanation.

Read GitHub's pull request documentation for more information on sending pull requests.

Lastly, please follow the pull request template when submitting a pull request!

Contributor License Agreement#

All third-party contributions to this project must be accompanied by a signed contributor license agreement. This gives Adobe permission to redistribute your contributions as part of the project. Sign our CLA. You only need to submit an Adobe CLA one time, so if you have submitted one previously, you are good to go!

Where to start#

There are many places to dive into react-spectrum to help out. Before you take on a feature or issue, make sure you become familiar with our architecture.

If you are looking for place to start, consider the following options:

  • Look for issues tagged with help wanted and/or good first issue.
  • Help triage existing issues by investigating problems and following up on missing information.
  • Update missing or fix existing documentation
  • Review and test open pull requests

Developing#

When you are ready to start developing you can clone the repo and start storybook. Make sure you have the following requirements installed: node (v11.0.0+) and yarn (v1.22.0+)

Fork the repo first using this guide, then clone it locally.

git clone https://github.com/YOUR-USERNAME/react-spectrum
cd react-spectrum
yarn install

You can then run the storybook and browse to http://localhost:9003 with:

yarn start

yarn start

yarn start

Or run the documentation and browse to http://localhost:1234/ with:

yarn start:docs

yarn start:docs

yarn start:docs

Tests#

We use jest for unit tests and react-testing-library for rendering and writing assertions. Please make sure you include tests with your pull requests. Our CI will run the tests on PRs as well as the linter and type checker. You can see on each PR whether you have passed all our checks. We split the tests into 2 groups.

Visual tests

  • A Storybook story should be written for each visual state that a component can be in (based on props).

Unit tests

  • (Props) Anything that should be changed by a prop should be tested via react-testing-library.
  • (Events) Anything that should trigger an event should be tested via react-testing-library.

You can run the tests with:

yarn jest

yarn jest

yarn jest

You can also get a code coverage report by running:

yarn jest --coverage

yarn jest --coverage

yarn jest --coverage

Linting#

The code is linted with eslint. The linter runs whenever you run the tests, but you can also run it with

yarn lint

yarn lint

yarn lint

TypeScript#

The code for React Spectrum is written in TypeScript. The type checker will usually run in your editor, but also runs when you run

yarn lint

yarn lint

yarn lint

Storybook#

We use Storybook for local development. Run the following command to start it:

yarn start

yarn start

yarn start

Then, open http://localhost:9003 in your browser to play around with the components and test your changes.

Documentation#

Our documentation should always remain up to date. When making changes to components, make sure the appropriate documentation has been updated to reflect those changes. Documentation for each component can be found in the docs folder within a component's package. Other documentation pages can be found in the packages/dev/docs folder in the codebase.

Documentation can be run locally by using

yarn start:docs

yarn start:docs

yarn start:docs

Then, open http://localhost:1234 in your browser.

Contributor to committer#

We love contributions from our community! If you'd like to go a step beyond contributor and become a committer with full write access and a say in the project, you must be invited. The existing committers employ an internal nomination process that must reach lazy consensus (silence is approval) before invitations are issued. If you feel you are qualified and want to get more deeply involved, feel free to reach out to existing committers to have a conversation.