Skip to content

Commit bc3bb57

Browse files
pczeglik-iohkpczeglik-iohk
authored
Merge pull request #16 from input-output-hk/docs-add-contributing-guide
docs: add CONTRIBUTING guide
2 parents 5a081f7 + 5f3bb12 commit bc3bb57

File tree

3 files changed

+128
-17
lines changed

3 files changed

+128
-17
lines changed

‎CONTRIBUTING.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Contributing
2+
3+
## Development workflow
4+
5+
To get started with the project, run `yarn` in the root directory to install the required dependencies:
6+
7+
```sh
8+
yarn
9+
```
10+
11+
We use [storybook](https://storybook.js.org/docs) for components development. To run storybook execute
12+
13+
```sh
14+
yarn dev
15+
```
16+
17+
## Linting and tests
18+
19+
We use [TypeScript](https://www.typescriptlang.org/) for type checking
20+
21+
```sh
22+
yarn type-check
23+
```
24+
25+
[ESLint](https://eslint.org/) for linting the code
26+
27+
```sh
28+
yarn lint
29+
```
30+
31+
and [Prettier](https://prettier.io/) for formatting the code
32+
33+
```sh
34+
yarn format
35+
```
36+
37+
> [!TIP] Pre-commit hook
38+
>
39+
> Our pre-commit hooks verify that the linter and format pass when committing.
40+
41+
We use [Chromatic](https://www.chromatic.com/docs/) for visual testing and UI regression.
42+
43+
Our storybook is published to Chromatic and accessible by following: [https://storybook.lw.iog.io/](https://storybook.lw.iog.io/)
44+
45+
## Commit message convention
46+
47+
We follow the [conventional commits specification](https://www.conventionalcommits.org/en) for our commit messages:
48+
49+
- `fix`: bug fixes, e.g. fix crash due to deprecated method.
50+
- `feat`: new features, e.g. add new method to the module.
51+
- `docs`: changes into documentation, e.g. add usage example for the module..
52+
- `style`: formatting, code style.
53+
- `refactor`: code refactor, e.g. migrate from class components to hooks.
54+
- `test`: adding or updating tests, e.g. add integration tests using detox.
55+
- `ci`: changes to continuous integration, pipelines, workflows.
56+
- `chore`: other changes not affecting functionality.
57+
58+
> [!TIP] Pre-commit hook
59+
>
60+
> Our pre-commit hooks verify that your commit message matches this format when committing.
61+
62+
### How to write good commit message
63+
64+
**Write the summary line of what you have done in the imperative mood**, that is as if you were
65+
commanding someone.
66+
67+
Start the line with `fix`, `add`, `change` instead of ~~`fixed`~~, ~~`added`~~, ~~`changed`~~.
68+
69+
Don’t end the summary line with a period`.`.
70+
71+
## Code Review
72+
73+
During the code review, we aim to improve the overall product quality.
74+
75+
- Reviews should be concise and written in neutral language. Critique the code, not the author, and be respectful.
76+
- Over-communicate your thoughts in the initial message, as it saves time on back and forth communication cycles.
77+
78+
### Merge Review
79+
80+
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.
81+
82+
Create atomic commits which focuses on single thing at a time, and write good commit message, so it is self-contained and explanatory.
83+
84+
## Versioning and Publishing
85+
86+
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).
87+
88+
> [!IMPORTANT]
89+
>
90+
> 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.
91+
92+
## Useful links
93+
94+
- [Auto-squashing Git Commits](https://thoughtbot.com/blog/autosquashing-git-commits)
95+
- [Code Review Developer Guide](https://google.github.io/eng-practices/review/)
96+
- [Respectful Code Reviews](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md)

‎README.md

+31-17
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# Lace UI toolkit
22

33
[![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)
4-
[![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)
54
[![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)
65
[![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)
76

@@ -19,12 +18,34 @@ yarn install
1918

2019
## Development
2120

22-
Storybook is used for development, run it using command:
21+
[Storybook](https://storybook.js.org/docs) is used for development, run it using command:
2322

2423
```bash
2524
yarn storybook
2625
```
2726

27+
or
28+
29+
```bash
30+
yarn dev
31+
```
32+
33+
For more details check [CONTRIBUTING.md]('./CONTRIBUTING.md) guide.
34+
35+
## File naming convention
36+
37+
| FILES | PURPOSE |
38+
| ---------------- | :----------------------------------------------------------------------------: |
39+
| \*.index.ts | Defines the public API to be imported by other modules |
40+
| \*.component.tsx | Defines the UI component |
41+
| \*.css.ts | Vanilla-extract CSS files |
42+
| \*.stories.ts | Storybook files |
43+
| \*.data.ts | Defines the data/types representation of the UI component or application logic |
44+
| \*.context.ts | Defines the UI component's inner state to be consumed by nested children |
45+
| \*.hooks.ts | Defines methods to manipulate the context state |
46+
47+
## Working with Storybook
48+
2849
### Stories format
2950

3051
| Type | PURPOSE |
@@ -49,25 +70,18 @@ export default {
4970
} as Meta;
5071
```
5172

52-
## File naming convention
73+
## Working with Icons
5374

54-
| FILES | PURPOSE |
55-
| ---------------- | :----------------------------------------------------------------------------: |
56-
| \*.index.ts | Defines the public API to be imported by other modules |
57-
| \*.component.tsx | Defines the UI component |
58-
| \*.css.ts | Vanilla-extract CSS files |
59-
| \*.stories.ts | Storybook files |
60-
| \*.data.ts | Defines the data/types representation of the UI component or application logic |
61-
| \*.context.ts | Defines the UI component's inner state to be consumed by nested children |
62-
| \*.hooks.ts | Defines methods to manipulate the context state |
75+
Adding a new or updating existing icons require:
6376

64-
### Icons
77+
1. Add svg icon to `src/icons/raw` directory.
78+
2. Run `build:icons` command (It will generate tsx components in `src/icons` directory and update `src/icons/index.ts`)
6579

66-
Adding new or updating existing icon require:
80+
```bash
81+
yarn build:icons
82+
```
6783

68-
1. Copy icon to `src/icons/raw` directory
69-
2. Run command `yarn build:icons`. It will generate tsx component in `src/icons` directory and update `src/icons/index.ts`
70-
3. Commit moved icon to raw directory and built component
84+
3. Commit all added and modified files.
7185

7286
To use icon in this project import it using lookup location `@icons/`
7387

‎package.json

+1
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"cleanup": "yarn run cleanup:dist && yarn run cleanup:nm",
2828
"cleanup:dist": "yarn exec rm -rf dist",
2929
"cleanup:nm": "yarn exec rm -rf node_modules",
30+
"dev": "yarn storybook",
3031
"format": "yarn prettier --write .",
3132
"format-check": "yarn prettier --check .",
3233
"lint": "yarn eslint --ext .ts,.tsx,.js,.jsx .",

0 commit comments

Comments
 (0)