CONTRIBUTING.md

Contributing

Scripts

# install
npm i --legacy-peer-deps

# run development env
npm run dev

# build
npm run build

# lint
npm run lint

# test (storybook must be running)
npm run test

# generate new custom-elements.json (updates storybook docs/args)
npm run analyze

# format all files with prettier
npm run format

Guidelines

1. Commits
   1. Commit messages MUST use Conventional Commit format.
   2. Certain commit types like fix: (patch), feat: (minor), and perf: (major) or BREAKING CHANGE: (in the commit body or footer, major), will automatically trigger a release to publish a new package and update the semantic version.
   3. Conventional Commits Cheat Sheet
   4. Git hooks are installed to enforce commit message formatting with commitlint, and code formatting with Prettier.
2. Branching
   1. main branch is for stable/current version changes.
   2. beta branch is for future version/prerelease/breaking changes.
   3. Prefix your branch names based on the type of change, ex feature/, bugfix/, or hotfix/.
   4. Use the GitHub Flow.
3. Code Review
   1. Always have someone peer review your PR.
   2. Status checks must pass.
   3. Strongly recommend using the Prettier extension to ensure consistent formatting.
4. Releases
   1. Releases will trigger automatically when the right commit messages are pushed to main or beta.
   2. All testing must be done on the PR level before merging, since the release will happen automatically after merge.
5. Creating Components
   1. Components should be contained within their own folder containing ts, scss, and stories files. Sub-components can share the same folder.
   2. Add new components to the root index.ts file.
   3. Everything in the design system should be 100% generic. Remember that these components could be used to build any application. Application concerns must be separated.
   4. Use Lit directives and decorators whenever possible.
   5. Build responsive, build clean, focus on style and performance, enhance with quick and smooth animations.
6. Documentation
   1. Document everything in your components with JSDoc.
   2. Update the custom-elements.json file with the npm run analyze script any time you add or change documentation. This is where the Storybook args tables are derived from.
   3. Write your storybook stories with controls enabled for every property where possible.
   4. When building modular components with sub-components, write multiple stories to show different variations. Include any sub-components in the main story so it renders a new tab with an args table.
7. Testing
   1. We use @storybook/test to execute a variety of automated tests.
      1. The Test Runner is used to execute Accessibility and Interaction tests both locally and in CI.
      2. Accessibility Tests
      3. Interaction Tests
         1. Interaction Test writing strategy TBD
   2. Visual Testing via Chromatic
      1. Provides visual screenshot comparison testing and a review process which integrates with our CI.

Third-Party Docs Reference

1. Chart.js
2. Lit
3. Storybook
4. @carbon/icons
5. @storybook/test
6. TypeScript
7. SCSS
8. Rollup