docs(contributing): reformat and fix typos, extend the committing guide (#1592)

CONTRIBUTING.md

@@ -2,66 +2,120 @@
 
 ## Reporting Issues
 
-If you have found what you think is a bug, please [start a discussion](https://github.com/pmndrs/zustand/discussions/new).
-
-Also for usage questions, please [start a discussion](https://github.com/pmndrs/zustand/discussions/new).
+If you have found what you think is a bug,
+and for usage questions,
+please [start a discussion].
 
 ## Suggesting new features
 
-If you are here to suggest a feature, first [start a discussion](https://github.com/pmndrs/zustand/discussions/new) if it does not already exist. From there, we will discuss use-cases for the feature and then finally discuss how it could be implemented.
+If you are here to suggest a feature,
+first [start a discussion] if it does not already exist.
+From there, we will discuss use-cases for the feature,
+and then finally discuss how it could be implemented.
+
+[start a discussion]: https://github.com/pmndrs/zustand/discussions/new
 
 ## Documentation
 
-- Fork the [Zustand repo](https://github.com/pmndrs/zustand/) into your own Github account
-- Locally, clone down your fork
-- Separately, clone the [Pmdrs-Website](https://github.com/pmndrs/website}
-  - this runs most of the doc websites under the pmndrs banner, including React Three Fiber and Zustand
-  - Switch to the `docs`-branch.
-- Now, you should have two repositories locally
-- Inside the website folder, run `npm install` and then `npm run dev`
-  - This will launch the website locally. You should be able to open and see the various documentation sites
-- One little catch here is that the website reads directly from Github, not locally. As a temporary measure, you can do the following (without actually committing these changes):
-  - Inside website codebase, open `src/data/libraries.ts`
-  - Within the `Zustand` key, change `docs: 'pmndrs/zustand/main/docs`, to `docs: '[username]/zustand/[test-branch]/docs'`,
-    - For example,`docs: 'chrisk-7777/zustand/docs-test/docs'`,
-  - Now, inside your Zustand fork, make the appropriate changes to the `.md` files in the `/docs` folder
-  - Push those changes up to your fork on a branch such as `docs-test` (_this should match whatever you set it to above in `libraries.ts`_
-  - Restart the website locally (`control + c` -> `npm run dev`)
-  - Visit the Zustand docs locally, and you should see the content you just pushed up
-- Once you are happy with your changes, commit them to a real branch and push up to your fork
-  - For now there are no formal naming conventions for branches.
-  - Commit messages follow a [conventional commit](#committing) style.
-- Jump back to the official repo (this one) and raise a PR from the branch you just pushed up
+If you want to contribute to the [documentation](./docs/):
+
+- [Fork Zustand](https://github.com/pmndrs/zustand/fork) into your Github account;
+- Clone your fork locally;
+- Separately, clone the [pmndrs/website repo](https://github.com/pmndrs/website)
+  (you don't need to fork it);
+  - This repo runs most of the doc websites under the pmndrs banner,
+    including React Three Fiber and Zustand
+  - Switch to the `docs` branch;
+- Now, you should have two repositories locally.
+- Inside the website directory, run `npm install` and then `npm run dev`;
+  - This will launch the website locally.
+    You should be able to open and see the various documentation sites.
+- One little catch here is that the website reads directly from Github, not locally.
+  As a temporary measure, you can do the following
+  (don't commit any changes made in the pmndrs/website repo):
+  - In your own Zustand fork, create a new working branch
+    (further related to as `[your-branch]`);
+  - Inside website codebase, open `src/data/libraries.ts`;
+  - Within the `zustand` key,
+    change `docs: 'pmndrs/zustand/main/docs'`
+    to `docs: '[your-username]/zustand/[your-branch]/docs'`;
+    - For example, `docs: 'chrisk-7777/zustand/docs-test/docs'`,
+  - Now, inside your Zustand fork,
+    make the appropriate changes to the documentation files in the `docs` folder;
+  - Commit and push those changes to `[your-branch]` in your Zustand fork;
+    - Commit messages follow the [conventional commits] style.
+      See the [committing guidelines].
+  - Restart the website locally (`control + c` -> `npm run dev`);
+    - Sometimes you may have to also remove the `temp` directory
+      in the website directory (`rm -r temp`);
+  - Visit the Zustand docs locally
+    and you should see the content you've just pushed.
+- Once you are happy with your changes:
+  - If you are okay with `[your-branch]` name, use it for the PR, or
+  - Create a new branch and push the changes to that one.
+  - For now there are no formal naming conventions for branches;
+- Jump back to the [official repo](https://github.com/pmndrs/zustand)
+  and open a PR from the branch you chose.
 
 ## Development
 
-If you would like to contribute by fixing an open issue or developing a new feature you can use this suggested workflow:
+If you would like to contribute by fixing an open issue
+or developing a new feature,
+you can use this suggested workflow:
 
-- Fork this repository.
-- Create a new feature branch based off the `main` branch.
-- Install dependencies by running `$ yarn`. [(version 1)](https://classic.yarnpkg.com/lang/en/docs/install)
-- Create failing tests for your fix or new feature.
-- Implement your changes and confirm that all test are passing. You can run the tests continuously during development via the `$ yarn test:dev` command.
-- If you want to test it in a React project you can either use `$ yarn link` or the `yalc` package.
-- Git stage your required changes and commit (see below commit guidelines).
-- Submit PR for review.
+- Fork this repository;
+- Create a new feature branch based on the `main` branch;
+- Install dependencies by running `yarn`
+  ([version 1](https://classic.yarnpkg.com/lang/en/docs/install));
+- Create failing tests for your fix or new feature;
+- Implement your changes and confirm that all test are passing.
+  You can run the tests continuously during development
+  with the `yarn test:dev` command.
+- If you want to test it in a React project:
+  - Either use `yarn link`, or
+  - Use the `yalc` package.
+- Commit your changes (see the [committing guidelines]).
+- Submit a PR for review.
+
+[committing guidelines]: #committing
 
 ### Committing
 
-We are applying the ideas of [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) here. In short that means that commit has to be one of the following (a _type_ in conventional commit speech):
+We are applying [conventional commits] here.
+In short, that means a commit has to be one of the following types:
 
-- **feat**: A new feature
-- **fix**: A bug fix
-- **docs**: Documentation only changes
-- **refactor**: A code change that neither fixes a bug nor adds a feature
-- **test**: Adding missing or correcting existing tests
-- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
-  generation
+- **feat**: A new feature.
+- **fix**: A bug fix.
+- **docs**: Documentation-only changes.
+- **refactor**: A code change that neither fixes a bug nor adds a feature.
+- **test**: Adding missing or correcting existing tests.
+- **chore**: Changes to the build process or auxiliary tools and libraries,
+  such as documentation generation
+
+If you are unfamiliar with the usage of conventional commits,
+the short version is to simply specify the type as a first word,
+and follow it with a colon and a space, then start your message
+from a lowercase letter, like this:
+
+```
+feat: add a 'BearStorage' storage type support
+```
+
+You can also specify the scope of the commit in the parentheses after a type:
+
+```
+fix(middleware): change the bear parameter in devtools
+```
+
+[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
 
 ## Pull requests
 
-Please try to keep your pull request focused in scope and avoid including unrelated commits.
+Please try to keep your pull requests focused and small in scope,
+and avoid including unrelated commits.
 
-After you have submitted your pull request, we'll try to get back to you as soon as possible. We may suggest some changes or improvements.
+After you have submitted your pull request,
+we'll try to get back to you as soon as possible.
+We may suggest some changes or improvements.
 
 Thank you for contributing! :heart: