CONTRIBUTING.md

Contributing

Getting started

The project requires a recent version of NodeJS and uses yarn as its package manager. See the .tool-versions file for the specific NodeJS version and use your version manager of choice (e.g. asdf or nvm) to install it.

Next, clone this repository, and install packages:

git clone [email protected]:bitcrowd/bitstyles.git
cd bitstyles
yarn install

Build

To build the whole library once, run

yarn build

To recompile the Sass on every change (while working on changes, for example):

yarn watch

Linting

This project uses stylelint and prettier to ensure code consistency. All PRs should be checked before merging:

yarn lint

You can also run linting on js, scss, or mdx files separately using the respective commands:

yarn lint:js
yarn lint:scss
yarn lint:docs

Some linting errors can be fixed automatically. For that there is the format command:

yarn format

Formatting can also be run separately on js, scss, and mdx:

yarn format:js
yarn format:scss
yarn format:mdx

Testing

After adding or changing anything that affects the final output CSS, you’ll need to update the fixtures. These record the expected state of the CSS output by the entire library in its default state, and when some configuration is being overidden.

Run the build & comparison:

yarn test

The output in terminal will show which lines differ from the current CSS output. This may be because of a bug introduced on the current branch, in which case the fixture should stay the same but your changes to source need to be corrected. If the change is expected, update the fixture to match, and commit the changes.

Component library

We use Storybook to provide a single navigable library of the classes in bitstyles, and the associated documentation.

When updating existing modules, be sure to update the necessary documentation in storybook, and provide meaningful stories that test the CSS, or illustrate its usage. When adding new modules, include a new <module name>.stories.mdx file, and follow the format of existing docs as best you can.

To view the storybook locally:

yarn storybook

Storybook will automatically open in a new tab in your default browser.

Deploying storybook documentation

The storybook documentation is automatically deployed when a branch is merged to main.