Merge pull request #16 from input-output-hk/docs-add-contributing-guide

docs: add CONTRIBUTING guide

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)

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/`
 

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 .",