diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e6b4d27 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contributing + +## Development workflow + +To get started with the project, run `yarn` in the root directory to install the required dependencies: + +```sh +yarn +``` + +We use [storybook](https://storybook.js.org/docs) for components development. To run storybook execute + +```sh +yarn dev +``` + +## Linting and tests + +We use [TypeScript](https://www.typescriptlang.org/) for type checking + +```sh +yarn type-check +``` + +[ESLint](https://eslint.org/) for linting the code + +```sh +yarn lint +``` + +and [Prettier](https://prettier.io/) for formatting the code + +```sh +yarn format +``` + +> [!TIP] Pre-commit hook +> +> Our pre-commit hooks verify that the linter and format pass when committing. + +We use [Chromatic](https://www.chromatic.com/docs/) for visual testing and UI regression. + +Our storybook is published to Chromatic and accessible by following: [https://storybook.lw.iog.io/](https://storybook.lw.iog.io/) + +## Commit message convention + +We follow the [conventional commits specification](https://www.conventionalcommits.org/en) for our commit messages: + +- `fix`: bug fixes, e.g. fix crash due to deprecated method. +- `feat`: new features, e.g. add new method to the module. +- `docs`: changes into documentation, e.g. add usage example for the module.. +- `style`: formatting, code style. +- `refactor`: code refactor, e.g. migrate from class components to hooks. +- `test`: adding or updating tests, e.g. add integration tests using detox. +- `ci`: changes to continuous integration, pipelines, workflows. +- `chore`: other changes not affecting functionality. + +> [!TIP] Pre-commit hook +> +> Our pre-commit hooks verify that your commit message matches this format when committing. + +### How to write good commit message + +**Write the summary line of what you have done in the imperative mood**, that is as if you were +commanding someone. + +Start the line with `fix`, `add`, `change` instead of ~~`fixed`~~, ~~`added`~~, ~~`changed`~~. + +Don’t end the summary line with a period`.`. + +## Code Review + +During the code review, we aim to improve the overall product quality. + +- Reviews should be concise and written in neutral language. Critique the code, not the author, and be respectful. +- Over-communicate your thoughts in the initial message, as it saves time on back and forth communication cycles. + +### Merge Review + +The PR commit messages plays an essential role in our versioning and publishing process. Rebase your branch with main to keep your code in sync and to have a linear commits history. + +Create atomic commits which focuses on single thing at a time, and write good commit message, so it is self-contained and explanatory. + +## Versioning and Publishing + +We follow [semantic versioning](https://semver.org/) and use [semantic release](https://github.com/semantic-release/semantic-release) for automatic versioning and publishing npm package to [GitHub Package Registry](https://github.com/input-output-hk/lace-ui-toolkit/pkgs/npm/lace-ui-toolkit). + +> [!IMPORTANT] +> +> It's important to follow [Commit message convention](#commit-message-convention), so semantic-release can automatically determine the right version to be published to registry. + +## Useful links + +- [Auto-squashing Git Commits](https://thoughtbot.com/blog/autosquashing-git-commits) +- [Code Review Developer Guide](https://google.github.io/eng-practices/review/) +- [Respectful Code Reviews](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md) diff --git a/README.md b/README.md index 5872aa3..fecbc3c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Lace UI toolkit [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=input-output-hk_lace-ui-toolkit&metric=alert_status&token=98802db7b585471a39ab75e8baf01cff96c561db)](https://sonarcloud.io/summary/new_code?id=input-output-hk_lace-ui-toolkit) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=input-output-hk_lace-ui-toolkit&metric=coverage&token=98802db7b585471a39ab75e8baf01cff96c561db)](https://sonarcloud.io/summary/new_code?id=input-output-hk_lace-ui-toolkit) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=input-output-hk_lace-ui-toolkit&metric=security_rating&token=98802db7b585471a39ab75e8baf01cff96c561db)](https://sonarcloud.io/summary/new_code?id=input-output-hk_lace-ui-toolkit) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=input-output-hk_lace-ui-toolkit&metric=vulnerabilities&token=98802db7b585471a39ab75e8baf01cff96c561db)](https://sonarcloud.io/summary/new_code?id=input-output-hk_lace-ui-toolkit) @@ -19,12 +18,34 @@ yarn install ## Development -Storybook is used for development, run it using command: +[Storybook](https://storybook.js.org/docs) is used for development, run it using command: ```bash yarn storybook ``` +or + +```bash +yarn dev +``` + +For more details check [CONTRIBUTING.md]('./CONTRIBUTING.md) guide. + +## File naming convention + +| FILES | PURPOSE | +| ---------------- | :----------------------------------------------------------------------------: | +| \*.index.ts | Defines the public API to be imported by other modules | +| \*.component.tsx | Defines the UI component | +| \*.css.ts | Vanilla-extract CSS files | +| \*.stories.ts | Storybook files | +| \*.data.ts | Defines the data/types representation of the UI component or application logic | +| \*.context.ts | Defines the UI component's inner state to be consumed by nested children | +| \*.hooks.ts | Defines methods to manipulate the context state | + +## Working with Storybook + ### Stories format | Type | PURPOSE | @@ -49,25 +70,18 @@ export default { } as Meta; ``` -## File naming convention +## Working with Icons -| FILES | PURPOSE | -| ---------------- | :----------------------------------------------------------------------------: | -| \*.index.ts | Defines the public API to be imported by other modules | -| \*.component.tsx | Defines the UI component | -| \*.css.ts | Vanilla-extract CSS files | -| \*.stories.ts | Storybook files | -| \*.data.ts | Defines the data/types representation of the UI component or application logic | -| \*.context.ts | Defines the UI component's inner state to be consumed by nested children | -| \*.hooks.ts | Defines methods to manipulate the context state | +Adding a new or updating existing icons require: -### Icons +1. Add svg icon to `src/icons/raw` directory. +2. Run `build:icons` command (It will generate tsx components in `src/icons` directory and update `src/icons/index.ts`) -Adding new or updating existing icon require: +```bash +yarn build:icons +``` -1. Copy icon to `src/icons/raw` directory -2. Run command `yarn build:icons`. It will generate tsx component in `src/icons` directory and update `src/icons/index.ts` -3. Commit moved icon to raw directory and built component +3. Commit all added and modified files. To use icon in this project import it using lookup location `@icons/` diff --git a/package.json b/package.json index e263699..b51c304 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "cleanup": "yarn run cleanup:dist && yarn run cleanup:nm", "cleanup:dist": "yarn exec rm -rf dist", "cleanup:nm": "yarn exec rm -rf node_modules", + "dev": "yarn storybook", "format": "yarn prettier --write .", "format-check": "yarn prettier --check .", "lint": "yarn eslint --ext .ts,.tsx,.js,.jsx .",