Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 9.03 KB

CONTRIBUTING.md

File metadata and controls

152 lines (109 loc) · 9.03 KB
Raw

Contributing to React-Rails

🎉 Thanks for taking the time to contribute! 🎉

With 5 Million+ downloads of the react-rails Gem and another 2 Million+ downloads of react_ujs on NPM, you're helping the biggest React + Rails community!

What follows is a set of guidelines for contributing to React-Rails, inside the react-js Organization, part of the wider React Community

By contributing to React-Rails, you agree to abide by the code of conduct.

How Can I Contribute?

Reporting Bugs

Before Submitting A Bug Report

  • Check the wiki. You might be able to find a guide on what you're experiencing. Most importantly, check if you can reproduce the problem in the latest version of React-Rails with React_ujs, sometimes we have already fixed the issue.
  • Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If the issue is closed open a new issue with reproduction steps and reference the old one.
  • If the problem is with pre-rendering, turn off pre-rendering and look at Chrome's developer console, that normally reveals more details about what the true error message is if it's a syntax error in a component or failing to require a component file.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. Create an issue and provide the following information by filling in the template.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it. For example, If you're using Browserify instead of Webpacker, how did you do it?
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, Gists, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.

Include details about your configuration and environment, React-Rails integrates many tools, versions of many things could be the culprit, though we try test as many as reasonable in our Travis Build

  • Which version of React-Rails are you using?
  • Which version of React_UJS are you using?
  • Which version of Shakapacker/Sprockets are you using?
  • Which version of Rails are you using?

Your First Code Contribution

Unsure where to begin contributing to React-Rails? You can start by looking through these help-wanted issues:

This issue list is sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.

Pull Requests

See git commit message style

  • Fill in the required template
  • Do not include issue numbers in the PR title
  • Include screenshots and animated GIFs in your pull request whenever possible.
  • Follow the styleguides where possible but readability is the most important!
  • Include intention-revealing Minitest tests in the ./test folder. It's important people know why a test exists by reading it more than what it does, we can read the source for the what.
  • Document new code where you're able.

Development

Local dev

Clone down the react-rails-example-app, it has several branches for different scenarios. It's designed to contain very simple examples of each feature of React-Rails.

To develop Ruby code, change the Gemfile to point to a local copy of react-rails.

gem 'react-rails', path: '../react-rails'

To develop the React_UJS NPM Package, make your changes and run npm pack to make a .tgz bundle, then in react-rails-example-app yarn add ../react_ujs-<version>.tgz

Running tests

Run yalc publish --push in the root directory of the gem to ensure the test suites use the exact same js code used in the currenlty developing ReactRails.

bundle exec appraisal install to install gems on every gemfile Appraisal contains. rake test or bundle exec appraisal rake test runs everything. or run a specific suite using bundle exec appraisal <appraisal name> rake test

  • Find appraisal names in Appraisals
  • Integration tests run in Headless Chrome which is included in Chrome (59+ linux,OSX | 60+ Windows)
  • ChromeDriver is included with chromedriver-helper gem so no need to manually install that 👍

Note: If using Ruby 2.7, set MT_KWARGS_HACK=1 to ensure Minitest runs smoothly.

Updating the pre-bundled react
  • Update React with rake react:update It outputs an ironically webpacked couple of files into lib/assets/react-source/<environment>/react(-server).js where it will be picked up by sprockets in lib/react/rails/asset_variant.rb
Updating ReactRailsUJS
  • Update the UJS with rake ujs:update
Releasing the Gem
  • (For Maintainers) To release a new RubyGems version:
    • Update the changelog (find recent changes on GitHub by listing commits or showing closed PRs)
    • Regular versions: bundle exec rake create_release\[2.7.0\]
    • RC versions: bundle exec rake create_release\[2.7.0.rc.2\]
    • Note, rake create_release runs rake react:update and rake ujs:update

Styleguides

Git Commit Messages

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
    • When only changing documentation, include [ci skip] in the commit description so we don't waste Travis's Open source resources.
  • Consider starting the commit message with an applicable emoji:
    • 🎨 :art: when improving the format/structure of the code
    • 🐎 :racehorse: when improving performance
    • 📝 :memo: when writing docs
    • 🐛 :bug: when fixing a bug
    • 🔥 :fire: when removing code or files
    • 💚 :green_heart: when fixing the CI build
    • ✅ :white_check_mark: when adding tests
    • 🔒 :lock: when dealing with security
    • ⬆️ :arrow_up: when upgrading dependencies
    • ⬇️ :arrow_down: when downgrading dependencies
    • 👕 :shirt: when removing linter warnings

Ruby styleguide

Ruby Style in this repo should attempt to follow the standard ruby styles as defined in Rubocop. This is more of a guide than a rule so use common sense, readability is more important than the style guide!

Issue and Pull Request Labels

Todo

Finally, thanks to the Atom Organization where this Contributing guide is based! ❤️ 💚