Skip to content

Latest commit

 

History

History
131 lines (99 loc) · 6.53 KB

CONTRIBUTING.md

File metadata and controls

131 lines (99 loc) · 6.53 KB
Raw

Contributing to Charts

Yippee! If you're here, you must be interested in contributing something to Charts.

If that's the case, we would like to personally thank you ahead of time 🤓❤️

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Table of contents

Run Charts in Local Environment

We use Lerna to manage all @carbon/charts related packages.

These are the Node & NPM versions we recommend:

  • Node Version: 12.16.1
  • Yarn Version: 1.6.0
  • NPM Version: 6.4.1

To get charts running locally on your machine:

  1. Fork this repo
  2. Clone your fork
  3. Run yarn (this would install all packages and get lerna setup)
  4. Run yarn build to do an initial build of the monorepo and correctly link all the packages

All packages use Storybook for demos:

yarn run storybook

Issue guidelines

  • Before submitting, confirm the issue doesn't already exist by browsing through existing issues. Duplicates are just a waste of space.
  • Keep issues specific to one topic. Do not open an issue that describes multiple defects.
  • Provide a short descriptive title that mentions the component being addressed.
  • Provide enough of the relevant information below to initiate a clear issue description. Most of this content comes out-of-the-box as a template when creating a new issue.
    • Type of issue
    • Version of charts
    • Description of the issue
    • Steps taken to produce the issue
    • Expected behavior
    • Current behavior
    • Screenshots or recording
    • Code snippets
    • Links to your application source code or running demo
      • Include any connection/authentication information we may need to view the links
  • Add relevant labels (accessibility, bug, design, discussion, feature, etc.) to help organize and identify issues. For a complete list of our labels, see the labels page.
  • If you are interested in contributing, feel free to assign the issue to yourself, otherwise leave it unassigned.

Pull request guidelines

  • Before creating the pull request:

    • Update the "[Unreleased]" section of CHANGELOG.md.

    • Update the demo as needed.

    • Update the documentation as needed.

    • Do not change the version number.

    • Keep in mind there will be a code review checklist against the following requirements at time of review:

      Requirement Description
      Demos all features All interactions spec'd out in the Design Guide has visual support and a demo as proof.
      Documented/annotated All rule blocks, placeholders, mixins, and functions has associated comment blocks that convey purpose and list inline notations referencing declarations that need further explanation.
      Matches UI/UX specs All features are pixel perfect when compared to the Design Guide.
      All new code follows similar structure and style to the existing codebase giving off the impression that it was written by one developer.
      Accessible All code passes the Dynamic Assessment Plugin (DAP) scan in Chrome.
      Mobile first All visual elements are elegantly responsive.
      RTL support All visual elements reflect bidirectional text appropriately.
      Performant All Sass code is strategically written in a way to limit bloat in the compiled CSS.

  • While creating the pull request:

    • Prepend "WIP: " to the title of your pull request if it is not ready to be merged.
    • Provide enough of the relevant information below to initiate a clear contribution description. Most of this content comes out-of-the-box as a template when creating a pull request.
      1. A list of updates with references to the related issue (see: Closing issues using keywords)
      2. Screenshots or recording
      3. @mention any key stakeholders that need to be aware of the changes
    • Add relevant labels (needs review, accessibility, bug, design, feature, etc.) to help organize and identify issues. For a complete list of our labels, see the labels page

Contribution process

  1. Run Charts locally, then configure the remotes from your charts/ directory:

    # Assign the original repo to a remote called "upstream"
git remote add upstream [email protected]:IBM/carbon-charts.git

  2. Create a new topic branch (off the original remote branch) to contain your code changes:

    git checkout -b <topic-branch-name> upstream/master

  3. Commit your changes in small logical chunks. Refer to these git commit message guidelines to maintain consistency.

    To commit changes, please use yarn run commit rather than git commit

  4. If time passes between development, locally merge (or rebase) the upstream master branch into your topic branch to avoid conflicts in your pull request. We recommend using Git's interactive rebase feature to tidy up a messy commit history.

    # Fetch and merge commits history
git pull upstream master
# Reapply one commit at a time
git rebase --interactive upstream/master

  5. Complete step 5 first, before pushing your topic branch up to your fork:

    git push origin <topic-branch-name>

  6. Open a Pull Request with a clear title and description from the template provided.

Code guidelines

Philosophy

  • Components should be fully equipped with all features and interactions defined in the latest Design Guide and UX Specifications.
  • Components should be pixel perfect when compared to the latest Design Guide.