mirror of
https://github.com/pmndrs/zustand.git
synced 2025-12-08 19:45:52 +00:00
docs: update CONTRIBUTING.md (#2986)
* docs: update CONTRIBUTING.md * docs(CONTRIBUTING.md): update documentation section including 'pnmdrs/docs' * docs(CONTRIBUTING.md): add period * docs(CONTRIBUTING.md): sepatate 'installing' and 'starting dev server' * docs(CONTRIBUTING.md): unify the tone of the command part
This commit is contained in:
Wonsuk Choi
GitHub
parent
bc3e94e991
commit
0beabe59bd
142
CONTRIBUTING.md
142
CONTRIBUTING.md
@ -1,95 +1,29 @@
|
||||
# Contributing
|
||||
|
||||
## Reporting Issues
|
||||
## General Guideline
|
||||
|
||||
If you have found what you think is a bug,
|
||||
and for usage questions,
|
||||
please [start a discussion].
|
||||
### Reporting Issues
|
||||
|
||||
## Suggesting new features
|
||||
If you have found what you think is a bug, please [start a discussion](https://github.com/pmndrs/zustand/discussions/new?category=bug-report).
|
||||
|
||||
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.
|
||||
For any usage questions, please [start a discussion](https://github.com/pmndrs/zustand/discussions/new?category=q-a).
|
||||
|
||||
[start a discussion]: https://github.com/pmndrs/zustand/discussions/new
|
||||
### Suggesting New Features
|
||||
|
||||
## Documentation
|
||||
|
||||
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:
|
||||
|
||||
- Fork this repository;
|
||||
- Create a new feature branch based on the `main` branch;
|
||||
- Install dependencies by running `pnpm 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 `pnpm test` command.
|
||||
- If you want to test it in a React project:
|
||||
- Either use `pnpm link`, or
|
||||
- Use the `yalc` package.
|
||||
- Commit your changes (see the [committing guidelines]).
|
||||
- Submit a PR for review.
|
||||
|
||||
[committing guidelines]: #committing
|
||||
If you are here to suggest a feature, first [start a discussion](https://github.com/pmndrs/zustand/discussions/new?category=ideas) 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.
|
||||
|
||||
### Committing
|
||||
|
||||
We are applying [conventional commits] here.
|
||||
In short, that means a commit has to be one of the following types:
|
||||
We are applying [conventional commit spec](https://www.conventionalcommits.org/en/v1.0.0/) here. In short, that means a commit has to be one of the following types:
|
||||
|
||||
Your commit type must be one of the following:
|
||||
|
||||
- **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.
|
||||
- **chore**: Changes to the build process, configuration, dependencies, CI/CD pipelines, or other auxiliary tools and libraries.
|
||||
- **docs**: Documentation-only changes.
|
||||
- **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,
|
||||
@ -97,24 +31,60 @@ 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
|
||||
feat: add a 'foo' 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
|
||||
fix(react): change the 'bar' parameter type
|
||||
```
|
||||
|
||||
[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
|
||||
### Development
|
||||
|
||||
## Pull requests
|
||||
If you would like to contribute by fixing an open issue or developing a new feature you can use this suggested workflow:
|
||||
|
||||
Please try to keep your pull requests focused and small in scope,
|
||||
and avoid including unrelated commits.
|
||||
#### General
|
||||
|
||||
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.
|
||||
1. Fork this repository.
|
||||
2. Create a new feature branch based off the `main` branch.
|
||||
3. Follow the [Core](#Core) and/or the [Documentation](#Documentation) guide below and come back to this once done.
|
||||
4. Run `pnpm run fix:format` to format the code.
|
||||
5. Git stage your required changes and commit (review the commit guidelines below).
|
||||
6. Submit the PR for review.
|
||||
|
||||
##### Core
|
||||
|
||||
1. Run `npm install` to install dependencies.
|
||||
2. Create failing tests for your fix or new feature in the [`tests`](./tests/) folder.
|
||||
3. Implement your changes.
|
||||
4. Run `pnpm run build` to build the library. _(Pro-tip: `pnpm run build-watch` runs the build in watch mode)_
|
||||
5. Run the tests by running `pnpm run test` and ensure that they pass.
|
||||
6. You can use `pnpm link` to sym-link this package and test it locally on your own project. Alternatively, you may use CodeSandbox CI's canary releases to test the changes in your own project. (requires a PR to be created first)
|
||||
7. Follow step 4 and onwards from the [General](#General) guide above to bring it to the finish line.
|
||||
|
||||
### Pull Requests
|
||||
|
||||
Please try to keep your pull request focused 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 request improvements, therefore, please check ✅ ["Allow edits from maintainers"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) on your PR.
|
||||
|
||||
## Zustand-specific Guideline
|
||||
|
||||
##### Documentation
|
||||
|
||||
Our [docs](https://zustand.docs.pmnd.rs) are based on [`pmndrs/docs`](https://github.com/pmndrs/docs).
|
||||
|
||||
1. Separately, clone the `pmndrs/docs`. (you don't need to fork it).
|
||||
2. Inside the `pmndrs/docs` directory:
|
||||
1. Create a `.env` file in the root directory with the next environment variables: `MDX=docs/zustand/docs` and `HOME_REDIRECT=/getting-started/introduction`.
|
||||
2. Run `npm install` to install dependencies.
|
||||
3. Run `npm run dev` to start the dev server.
|
||||
4. Navigate to [`http://localhost:3000`](http://localhost:3000) to view the documents.
|
||||
3. Go Back to the forked repository:
|
||||
1. Run `pnpm install` to install dependencies.
|
||||
2. Navigate to the [`docs`](./docs/) folder and make necessary changes to the documents.
|
||||
3. Add your changes to the documents and see them live reloaded in the browser. (if you don't see changes, try `control + c`, then run `npm run dev` in the cloned `pnmdrs/docs` repository)
|
||||
4. Follow step 4 and onwards from the [General](#General) guide above to bring it to the finish line.
|
||||
|
||||
Thank you for contributing! :heart:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user