How to Write a Pull Request for Reaction

We’re always on the lookout for new contributors, whether they’re JavaScript newbies or seasoned devs. As our project and community expand to all corners of the globe, it’s up to the Reaction core team to define the rules for communication: how to propose, collaborate on, and successfully merge new code from all walks of life. If you’re looking to submit your work to our project repo, then you’ll want to read on. Here are the elements of a great pull request, along with some tangible examples from the community.

A useful title

It’s surprising how much information you can pack into one line of copy. Here’s an example from Brent (@zenweasel).

alt

A useful title might contain:

  • An issue key detailing the issue number associated with your PR.
  • A descriptive title that summarizes what’s being solved in 50 characters or less. This provides the core team with just enough context around the problem without too much preamble.
  • Imperative present tense verbs, eg. “fix bug” as opposed to “fixed bug.”
  • [WIP], which is a simple way of indicating that the PR is a work in progress, and may not be ready for feedback yet.

A clear summary

If your pull request isn’t linked to an existing issue, then it’s up to you to provide detailed information on the purpose of the PR. This is where you lay out your goals, plain and simple, much like the abstract of a research paper. Take a look at #2808:

alt

Not only will this help you stay organized, it’ll also help us keep track of all your contributions during code review.

A clear summary might contain:

  • Bullet points, hyphens, or asterisks to break your points down
  • Hanging indents
  • The main objectives, as well as any other new information that’s being introduced. In this example, Spencer (@spencern) not only broke down the four main objectives of his PR, but also highlighted a new concept: event logging on products and variants.

Testing instructions

Be sure to provide detailed instructions on how we can test your PR locally. This way, we can verify your contributions efficiently, which means your code will get merged faster.

alt

In #2932, @Akarshit listed his step-by-step process for testing out his code.

Screenshots

Sometimes, it’s easier to show than tell. Screenshots should illustrate what the issue looks like; it should also provide some context as to how the behavior might look like once it’s resolved. Take a look at #2907:

alt

Checks that pass successfully

alt

To ensure that all code contributions are ready for release, all PRs should adhere to and pass the following set of tests:

  • bitHound code analysis - Checks the code for linting. We recommend you locally run eslint in the root directory before pushing your code to GitHub.
  • bitHound dependencies analysis - Checks the code to make sure all npm dependencies are up to date.
  • CI/CircleCI tests - Ensures that the app and its functionality still work as intended after changes are made. Before opening up a PR, you can (and should!) run reaction test to test locally.
  • Snyk - Checks for any security or vulnerability issues.

Other general tips:

  • Follow the Reaction style guide.
  • Make small, frequent requests. PRs that are smaller in scope are easier for the team to review, merge, and approve.
  • Be as detailed as possible. Provide us with labels. Include as many screenshots as possible.
  • Be sure to read our conduct guidelines before opening an issue or submitting a PR.
  • Don’t be afraid to collaborate! Tag other people in your PR. Add comments for your reviewer. Send us gifs, use emoji—interact with us! We won’t bite.

Ready to submit a pull request?

Great! Go ahead and explore our open issues on GitHub. Anything with the pull-requests-encouraged label is fair game. And in case you didn’t know, we're giving away t-shirts, tote bags, and $500 gift cards to anyone who contributes a feature or fixes a bug from now until December 15. Want to learn more? Check out the official rules for the Reaction Hack-a-bug-a-thon.

If you're interested in a particular project and you aren’t sure where to begin, feel free to ask us via Gitter. Looking forward to your contributions! See you on GitHub.

comments powered by Disqus