Skip to content

Latest commit

 

History

History
155 lines (126 loc) · 4.95 KB

CONTRIBUTING.MD

File metadata and controls

155 lines (126 loc) · 4.95 KB
Raw

Reporting Issues and Asking Questions

Before opening an issue, please search the issue tracker to make sure your issue hasn't already been reported.

Development

Visit the Issue tracker to find a list of open issues that need attention.

Clone the repo:

git clone git@github.com:instacart/Snacks.git

Then install dependencies:

cd ./Snacks
yarn

or

cd ./Snacks
npm install

Working on a component

Start stylguide locally

yarn styleguide

or

npm run styleguide

Go to http://0.0.0.0:6060 to see all components. This environment has hot reloading and components can be added on the fly though the various doc files. Look for any file in a component's folder with .md for examples of component code that the styeguide will run automatically.

You can also enable continous testing (linting, snapshot and unit tests) on every file save by following instructions in the testing step below.

Building

Running the build task will run tests and create a lib/dist.js file

yarn build

or

npm run build

Running the styleguide:build command will generate a static style guide site under the styleguide directory

yarn styleguide:build

or

npm run styleguide:build

Testing

To run tests:

yarn test

or

npm test

To continuously watch and run tests, run the following:

yarn test:watch

or

npm run test:watch

Submitting Changes

  • If it's a bug fix, open a new issue in the Issue tracker.
  • Create a new feature branch based off the master branch.
  • Make sure all tests pass.
  • Submit a pull request, referencing any issues it addresses.

Please try to keep your pull request focused in scope and avoid including unrelated commits.

If you're creating a new component, that component must be snapshot tested and follow the general coding practices

Creating a new component

New components must:

  • have comprehensive tests
  • have comprehensive documentation
  • follow our code conventions
  • be reviewed and approved

Code Conventions

  • Do not use semicolons ;
  • 2 spaces for indentation (no tabs)
  • Prefer ' over "
  • 120 character line length (except documentation)
  • Readability over trickiness or performance
  • Use the decorator pattern when applicable - ie @Radium
  • Create stateless components when possible
  • Create React PureComponents if not stateless
  • Create es6 classes inheriting from React's Component class if not pure or stateless
  • Always include propTypes with as much specificity as possible - ie propTypes.shape is better than propTypes.object

Linting will run when you run tests, and most of the above rules will be caught.

Tests

Tests are done using a few frameworks/libraries:

  • Jest - Snapshot tests + assertion library
  • Sinon - Spies for testing function calling
  • Enzyme - Testing DOM interactions like clicking

Tests are co-located with their components in a __tests__ directory and are named ComponentName.spec.js, per Jest convention.

Test Conventions

  • Reliable over comprehensive
  • Simple over convoluted
  • Fast over slow

Documentation

Documentation is generated by React Styleguidist and can be augmented by a combination of JSDoc comments and by adding readme files for your components. Readme files for new components are required, and should be co-located with your component under a docs directory and be named <YourComponent>.md.

Running the styleguide command will start up a local server running the style guide on http://localhost:6060

yarn styleguide

or

npm run styleguide

Running the styleguide:build command will generate a static style guide site under the top-level docs directory. This gets built and hosted at https://instacart.github.io/Snacks/

yarn styleguide:build

or

npm run styleguide:build

Releasing a new version of Snacks

Two factor authenticaion is required on your npm account. You'll need your authenticator code during the release step.

  1. npm run release:build If you run into test failure issues that aren't your own (eg: snapshot failures), remember to yarn install once to get the right dependencies If you run into "0.0.xyz" branch already exists, switch back to master and delete that branch so you can start again. Make sure your code is the lastest from the master branch.
  2. Go to the branch created on Github and update the description of the release branch to include a list of new components, enhancements, fixes or other important changes.
  3. Merge the branch into master on Github
  4. Draft a new release with the same description as the release branch: https://github.com/instacart/Snacks/releases
  5. npm run release:publish