11# Contributing
22
3- First of all, thanks for contributing to ` @react-hookz ` ! The collective developing and
4- using this library appreciates your efforts.
3+ First of all, thanks for contributing to ` @react-hookz ` ! The collective developing and using this library appreciates
4+ your efforts.
55
66If you are contributing for the first time, we recommend reading this
77[ First Contributions guide] ( https://github.com/firstcontributions/first-contributions ) first.
@@ -18,69 +18,60 @@ If you are contributing for the first time, we recommend reading this
1818 - if your change fixes an issue, name the branch based on the issue number: ` pr/fix-12345 `
19197 . Follow the directions below:
2020
21- > ** Tip:** to keep your ` master ` branch pointing to the original repo's ` master ` (instead of your
22- > fork's ` master ` ) do this:
21+ > ** Tip:** to keep your ` master ` branch pointing to the original repo's ` master ` (instead of your fork's ` master ` ) do
22+ > this:
2323>
2424> ``` shell
2525> git remote add upstream https://github.com/react-hookz/web.git
2626> git fetch upstream
2727> git branch --set-upstream-to=upstream/master master
2828> ` ` `
2929>
30- > After running these commands you' ll be able to easily pull changes from the original repository
31- > with
32- > `git pull`.
30+ > After running these commands you' ll be able to easily pull changes from the original repository with `git pull`.
3331
3432## Development
3533
36- 0. Perform self-check on hook usefulness. We' re not interested in hooks that has too specific
37- usecase or hooks that can be easily achieved by composition of existing hooks.
34+ 0. Perform self-check on hook usefulness. We' re not interested in hooks that has too specific usecase or hooks that can
35+ be easily achieved by composition of existing hooks.
38361. Implement the hook in the ` src` folder.
39- - The file with hook implementation should be named ` index.ts` and placed in a subdirectory
40- named after the hook.
37+ - The file with hook implementation should be named ` index.ts` and placed in a subdirectory named after the hook.
4138 - The hook should have return types explicitly defined.
42- - The hook should have a JSDoc comment containing a description of the hook and an overview of
43- its arguments.
39+ - The hook should have a JSDoc comment containing a description of the hook and an overview of its arguments.
4440 - The hook should be exported by name, not default-exported.
45- - If the hook has custom types in its parameters or return values, they should be exported as
46- well.
41+ - If the hook has custom types in its parameters or return values, they should be exported as well.
4742 - Types and interfaces should not have prefixes like ` I` or ` T` .
48- - The hook should be developed with SSR in mind, meaning that usage of hook in SSR environment
49- should not lead to errors.
50- - If your hook reuses other @react-hookz/web hooks, import them as
51- ` import { useToggle } from ' ../useToggle' ; ` instead of
52- ` import { useToggle } from ' ..' ; `
43+ - The hook should be developed with SSR in mind, meaning that usage of hook in SSR environment should not lead to
44+ errors.
45+ - If your hook reuses other @react-hookz/web hooks, import them as ` import { useToggle } from ' ../useToggle' ; `
46+ instead of ` import { useToggle } from ' ..' ; `
53472. Re-export the hook implementation and all its custom types in ` src/index.ts` .
54483. Fully test your hook. The tests should include tests for both DOM and SSR environments.
55- - Hook' s tests should be placed in `__tests__` subdirectory, next to the source file - `dom.ts`
56- for DOM environment, `ssr.ts` for SSR environment.
57- For example: `src/useFirstMountState/__tests__/dom.ts`
58- and `src/useFirstMountState/__tests__/ssr.ts`.
59- - Ideally, your hook should have 100% test coverage. If that is impossible, you should leave a
60- comment in the code describing why.
61- - Each hook should have at least `' should be defined' ` and `' should render' ` tests in `SSR`
62- environment.
49+ - Hook' s tests should be placed in `__tests__` subdirectory, next to the source file - `dom.ts` for DOM environment,
50+ `ssr.ts` for SSR environment.
51+ For example: `src/useFirstMountState/__tests__/dom.ts` and `src/useFirstMountState/__tests__/ssr.ts`.
52+ - Ideally, your hook should have 100% test coverage. If that is impossible, you should leave a comment in the code
53+ describing why.
54+ - Each hook should have at least `' should be defined' ` and `' should render' ` tests in `SSR` environment.
6355 - All utility functions should also be tested.
64564. Write docs for your hook.
6557 - Docs should be placed in `__docs__` sub-folder, near the source file.
6658 For example: `src/useFirstMountState/__docs__/story.mdx`.
6759 - Docs are built with Storybook. You can run `yarn storybook:watch` to preview your work.
68- - Write a short example demonstrating your hook in `example.stories.tsx` within the `__docs__`
69- folder. (If the filename misses the `.stories.tsx` part, Storybook won' t find your example.)
60+ - Write a short example demonstrating your hook in `example.stories.tsx` within the `__docs__` folder. (If the
61+ filename misses the `.stories.tsx` part, Storybook won' t find your example.)
7062 For example: ` src/useFirstMountState/__docs__/example.stories.tsx` .
7163 - Docs are written in MDX format.
7264 [Read more about storybook docs](https://storybook.js.org/docs/react/writing-docs/introduction).
73655. Add a summary of the hook and a link to the docs to ` README.md` .
74- 6. After all the above steps are done, run ` yarn lint:fix` to ensure that everything is styled by
75- our standards and there are no linting issues.
66+ 6. After all the above steps are done, run ` yarn lint:fix` to ensure that everything is styled by our standards and
67+ there are no linting issues.
76687. ` yarn new-hook myAwesomeHook` will help you to create a proper file structure for the new hook.
7769
7870# ## Notes on porting a hook from `react-use`
7971
80- - Check from # 33 and the [migration guide](src/__docs__/migrating-from-react-use.story.mdx) that the
81- hook has been approved for porting. If there is no previous discussion on the hook in #33, leave a
82- comment there asking if you could port the hook. In your comment, provide a valid use-case for the
83- hook.
72+ - Check from # 33 and the [migration guide](src/__docs__/migrating-from-react-use.story.mdx) that the hook has been
73+ approved for porting. If there is no previous discussion on the hook in #33, leave a comment there asking if you could
74+ port the hook. In your comment, provide a valid use-case for the hook.
8475- Don't just copy-paste the hook. Think through the code:
8576 - Is there sufficient tests?
8677 - Could the hook be implemented by reusing existing hooks in ` @react-hookz/web` ?
@@ -92,9 +83,8 @@ If you are contributing for the first time, we recommend reading this
9283# ## Commit message
9384
9485This repo uses [semantic-release](https://github.com/semantic-release/semantic-release) and
95- [conventional commit messages](https://conventionalcommits.org) so prefix your commits with ` fix:` ,
96- ` feat:` , etc., so that your changes appear in the
97- [release notes](https://github.com/react-hookz/web/blob/master/CHANGELOG.md).
86+ [conventional commit messages](https://conventionalcommits.org) so prefix your commits with ` fix:` , ` feat:` , etc., so
87+ that your changes appear in the [release notes](https://github.com/react-hookz/web/blob/master/CHANGELOG.md).
9888
9989Also, there is a script that helps you to properly format commit messages:
10090
@@ -103,11 +93,11 @@ git add .
10393yarn commit
10494` ` `
10595
106- The script guides you through several prompts that help you with writing a good commit message,
107- including many non-obvious and easy-to-forget parts.
96+ The script guides you through several prompts that help you with writing a good commit message, including many
97+ non-obvious and easy-to-forget parts.
10898
10999# ## Git hooks
110100
111- This project includes Git hooks that are automatically enabled when you install the dependencies.
112- These hooks automatically test and validate your code and commit messages before each commit. In
113- most cases disabling these hooks is not recommended.
101+ This project includes Git hooks that are automatically enabled when you install the dependencies. These hooks
102+ automatically test and validate your code and commit messages before each commit. In most cases disabling these hooks is
103+ not recommended.
0 commit comments