Skip to content

Latest commit

 

History

History
192 lines (135 loc) · 8.88 KB

CONTRIBUTING.md

File metadata and controls

192 lines (135 loc) · 8.88 KB
Raw

Contributing Guide

Setup

Getting setup to contribute

  1. Fork repository by clicking the fork button on github
  2. Clone repository with git clone https://github.com/<your handle>/britecharts-react.git
  3. Navigate to the repository folder and install dependencies with: yarn install (we require node 6.11.x at the moment)
  4. If you don't have yarn installed, it can be easily installed with homebrew following the instruction in the yarn docs

Creating feature branches

  1. in local master, set upstream to https://github.com/eventbrite/britecharts-react.git

    git remote add upstream https://github.com/eventbrite/britecharts-react.git

  2. pull the most recent changes by rebasing master

    git pull --rebase upstream master

  3. Branch names should be prefixed with either fix- or feat- depending on your PR content. Create a new branch by typing:

    git checkout -b [fix|feat]-<your branch name>

Running the Demos

In order to generate the demos and see the documentation for the library you would need to:

  • Download and install node (note we need npm version 2.X)

  • Ensure you have yarn installed as well

  • Clone the repository with:

    git clone git@github.com:eventbrite/britecharts-react.git

  • Change directory into the repository root and install its dependencies:

    yarn install

  • In the root or the repository folder, run:

    yarn run test

  • In a second terminal window, run:

    yarn run styleguide

This process will generate the styleguide and show it in localhost:6060. You can use this demos as your testing platform when creating new charts.

Modifying a chart

We have created this components with Tests First, and we encourage you to do the same. However, you can also write tests later.

For a TDD workflow, the process would look like this:

  1. Create a new branch for your modification
  2. On a new terminal, run yarn start and yarn run styleguide and navigate to the chart's demo or create a new demo in /src/charts/*/Readme.md
  3. Find the test of the chart you want to modify in /src/charts/*/*.test.js
  4. Write a failing test for the feature you want to add
  5. On a new terminal, run yarn run test:watch
  6. Check that the test fail
  7. Write the code that would make that test pass on the chart located in /src/charts/*/*Component.js or /src/charts/*/*Chart.js. Please follow the code style in the current files.
  8. Make the test pass by writing the less amount of code
  9. Refactor until you get a nice and clean code
  10. Check the demo to see the code in action
  11. Update the documentation so that the proper demos gets generated when you run yarn run styleguide:build
  12. Create a pull request and ask people of the team to review it
  13. Once you have the OK, merge it!

Creating a new chart

Adding a new chart is a bunch of work, but we hope that using the current code and documentation will help in the process.

  1. Create a new branch for your new chart
  2. On a new terminal, run yarn start yarn run styleguide to get ready the demos and turn on the dev server.
  3. Given that you new chart is ChartName, create in /src/charts/ChartName a new file ChartName.js and test file ChartName.test.js.
  4. Create also a new component in /src/charts/ChartName a new file ChartNameComponent.js and test file ChartNameComponent.test.js.
  5. Add the new demo entry on /src/charts/ChartName/Readme.md, keeping the same format.
  6. Go to webpack.config.js and add the new chart to the CHARTS object, follow the same style.
  7. Go to your test file ChartName.test.js and, taking another test as an example, copy over pieces until you have the first test case.
  8. Add one test and make it fail calling yarn run test:watch.
  9. Keep on coding according to the code style you can see in the current charts, using the stackedAreaChart as a reference.
  10. Generate your docs with yarn run styleguide:build and manually test the demos.
  11. Create a pull request with your branch and ping one of the core authors to get it reviewed.
  12. Once you have a shipit, merge it

Alternatively, you can use Plop to generate the boilerplate for your new component, if the component already exists in Britecharts.

  1. Create a new branch for your new chart
  2. On a new terminal, run yarn start yarn run styleguide to prepare the demos and turn on the dev server.
  3. On a new terminal, run yarn run plop. When prompted, enter your chart's name (be sure to use PascalCase capitalization!). This will generate a new folder for your component in src/charts/chartName, with all necessary files.
  4. Before starting to modify the boilerplate, start the test suite: yarn run test:watch.
  5. Follow the tasks in src/charts/chartName/Checklist.md to complete your component
  6. Once completed, create a pull request with your branch and ping one of the core authors to get it reviewed.
  7. Once you have a shipit, merge it

Pull Requests

Disclaimer -> While it is true that Britecharts-React is currently live in Eventbrite production, this project is not being monitored closely for open source contributions. Please have patience and we will get to any issues and pull requests as soon as we can.

Making pull requests

1- when you're finished coding, git checkout master 2- git pull upstream master (note that your local master should always reflect upstream master) 3- git checkout <your branch> 4- git rebase master & reconcile all conflicts 5- git push origin <your branch> 6- make your pr with a link to the original issue filed (if you see "unable to merge", please pull from your upstream and rebase again) 7- be patient :)

Reporting an Issue/Feature Requests

Please use the issues section of the Britecharts-React github profile to submit any bugs found. Please be descriptive and feel free to add pictures or links to docs to make your point as clear as possible.

The Workflow

yarn Tasks

The build sequence consists of a small set of Node tasks. While you'll probably only need yarn run test and yarn run build most of the time, the other tasks can be called independently or combined in order to see the docs.

Task Description
yarn run start Start the development process that is going to transpile the files
yarn run test Run the Jest runner to see if the tests are running
yarn run test:watch Start the Jest runner that will test the project and keep watching for changes.
yarn run styleguide Serves the demos in localhost:6060.
yarn run styleguide:build Builds the styleguide.
yarn run build Build everything and generate the distribution version of the charts.
yarn run lint Runs the eslint linter
yarn run lint:fix Runs the eslint linter fixing easy problems
yarn run release Create a new release of the library.
yarn run release:minor Create a new release of the library by bumping the second number of the version (1.N.1)
yarn run release:major Create a new release of the library by bumping the third number of the version (N.1.1)

Project Structure

The default directory structure looks something like this:

britecharts-react
├── dist
├── docs
├── lib
├── src
│   ├── charts
│   ├── docs
│   ├── helpers
│   └── tasks
Folder Description
dist Where the production ready bundle of our charts will be placed
docs Where the generated demo website lives
lib Where the production ready individual UMD bundles will live, alongside with the ES6 modules version of them
src Where we will place the code we create
src/charts Where our charts live
src/charts/helpers Where our chart helpers live
src/helpers Where our general helpers live, like test data generators
src/tasks Some of our grunt tasks configuration