Skip to content

Latest commit

 

History

History
215 lines (130 loc) · 8.46 KB

CONTRIBUTING.md

File metadata and controls

215 lines (130 loc) · 8.46 KB
Raw

Contribution Guidelines

Want to contribute to this repository? Please read below first:

Issues and Bugs

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to this repo. Even better you can submit a Pull Request with a fix.

Please see the Submission Guidelines below.

Feature Requests

You can request a new feature by submitting an issue to this repo. Proposed features (with suitable design documentation and reasoning) can be crafted and submitted to this repo as a Pull Request.

Please see the Submission Guidelines below.

Doc Fixes

If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Comment on an issue to let others know what you're working on, or create a new issue if your work doesn't fit within the scope of any of the existing doc fix projects.

Please see the Submission Guidelines below.

Submission Guidelines

Setup

  1. Fork the project by navigating to the main repository and clicking the Fork button on the top-right corner.

  2. Navigate to your forked repository and copy the SSH url. Clone your fork by running the following in your terminal:

    $ git clone [email protected]:{ YOUR_USERNAME }/carbon-components-react.git
$ cd carbon-components-react

    See GitHub docs for more details on forking a repository.

  3. Once cloned, you will see origin as your default remote, pointing to your personal forked repository. Add a remote named upstream pointing to the main carbon-components-react:

    $ git remote add upstream [email protected]:IBM/carbon-components-react.git
$ git remote -v

Submitting an Issue

Before you submit your issue, search the repository. Maybe your question was already answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.

Submitting a Pull Request

  1. Search this repository for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort.

  2. Pull the latest master branch from upstream:

    $ git pull upstream master

  3. Always work and submit pull requests from a branch. Do not submit pull requests from the master branch of your fork.

    $ git checkout -b { YOUR_BRANCH_NAME } master

  4. Create your patch or feature following our development guidelines. Make sure to also follow our coding standards.

  5. Test your branch and add new test cases where appropriate per the testing guidelines.

  6. Commit your changes using a descriptive commit message.

    $ git commit -a -m "chore: Update header with newest designs, resolves #123"

    Note: the optional commit -a command line option will automatically "add" and "rm" edited files. See Close a commit via commit message and writing good commit messages for more details on commit messages.

  7. Once ready for feedback from other contributors and maintainers, push your commits to your fork (be sure to run yarn ci-check before pushing, to make sure your code passes linting and unit tests):

    $ git push origin { YOUR_BRANCH_NAME }

  8. In Github, navigate to IBM/carbon-components-react and click the button that reads "Compare & pull request".

  9. Write a title and description, the click "Create pull request".

    See how to write the perfect pull request for more details on writing good PRs.

  10. Stay up to date with the activity in your pull request. Maintainers will be reviewing your work and making comments, asking questions and suggesting changes to be made before they merge your code. When you need to make a change, add, commit and push to your branch normally.

    Once all revisions to your pull request are complete, a maintainer will squash and merge your commits for you.

That's it! Thank you for your contribution!

Coding Standards

To ensure consistency throughout the source code, keep these rules in mind as you are working:

Style Guide

For a set of basic rules and guidelines for developing React components, see here.

Feel free to edit/write components in your own style but be wary that we may ask you to make changes while reviewing your pull request.

Linting

We enforce some style rules for code in this repository using eslint. You can install a linting addon to a lot of editors and IDEs that will follow our linting rules.

If you decide to not install a linter addon, or cannot, you can run yarn lint to get a report of any style issues. Any issues not fixed will be caught during CI, and will prevent merging.

Commit Message Guidelines

We use commit message guidelines based on the Angular Commit Conventions.

Please stick to the following format: git commit -m "<type>(<scope>): <message>"

  • Replace <type> with one of following: feat, fix, docs, style, refactor, perf, test, chore, revert.
  • The (<scope>) is optional and could be anything specifying the place of the commit change.

After the commit message has been submitted, it is checked by husky and validate-commit-msg to ensure it is syntactically correct.

Testing

If you add any features to our code, make sure to add tests so that your changes are covered. Tests are written using JEST. You can see how well your code is covered by looking at the .gh-pages/coverage/lcov-report/index.html file after running the coverage command.

Test your changes by running our test commands:

  • Run linting:

    yarn lint

  • Run unit tests:

    yarn test

  • Run both linting and unit tests:

    yarn ci-check

  • Watching unit tests:

    yarn test --watch

  • Generate code coverage report (stored in .gh-pages/coverage folder):

    yarn test --coverage

Storybook

We recommend the use of React Storybook for developing components.

  1. (Optional) Set environment variables:

    • true to CARBON_USE_BREAKING_CHANGES environment variable to test some of the breaking changes for the next release:

      $ export CARBON_USE_BREAKING_CHANGES=true

    • true to CARBON_REACT_STORYBOOK_USE_EXTERNAL_CSS environment variable to use external CSS, making style source link usable in DOM inspector:

      $ export CARBON_REACT_STORYBOOK_USE_EXTERNAL_CSS=true

    • true to CARBON_REACT_STORYBOOK_USE_STYLE_SOURCEMAP environment variable to use Sass source map, making style source link point to the original Sass code:

      $ export CARBON_REACT_STORYBOOK_USE_STYLE_SOURCEMAP=true

    • true to CARBON_USE_EXPERIMENTAL_FEATURES environment variable to test some of the experimental changes:

      $ export CARBON_USE_EXPERIMENTAL_FEATURES=true

Caveats:

  • CARBON_REACT_STORYBOOK_USE_EXTERNAL_CSS=true and CARBON_REACT_STORYBOOK_USE_STYLE_SOURCEMAP=true make WebPack builds slightly slower.
  • With CARBON_REACT_STORYBOOK_USE_STYLE_SOURCEMAP=true, the source map (hitting style source link in DOM inspector) sometimes leads you to a mix-in, instead of a style rule calling the mix-in, which may get you lost.

  1. Start the server:

    $ yarn storybook

  2. Open browser to http://localhost:9000/.

  3. Develop components in their respective folders (/components or /internal).

  4. Write stories for your components next to the components themselves, for example Checkbox.js would have Checkbox-story.js in the same folder.