diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ee72901..21b32a7c 100644 --- a/CONTRIBUTING.md +++ b/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: