|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Questions |
| 4 | + |
| 5 | +If you have questions about implementation details, help or support, then please use our dedicated community forum at [Github Discussions](https://github.com/tannerlinsley/react-query/discussions) **PLEASE NOTE:** If you choose to instead open an issue for your question, your issue will be immediately closed and redirected to the forum. |
| 6 | + |
| 7 | +## Reporting Issues |
| 8 | + |
| 9 | +If you have found what you think is a bug, please [file an issue](https://github.com/tannerlinsley/react-query/issues/new). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [Github Discussions](https://github.com/tannerlinsley/react-query/discussions) |
| 10 | + |
| 11 | +## Suggesting new features |
| 12 | + |
| 13 | +If you are here to suggest a feature, first create an issue 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. |
| 14 | + |
| 15 | +## Development |
| 16 | + |
| 17 | +If you have been assigned to fix an issue or develop a new feature, please follow these steps to get started: |
| 18 | + |
| 19 | +- Fork this repository |
| 20 | +- Install dependencies by running `$ yarn` |
| 21 | +- Link `react-query` locally by running `$ yarn link` |
| 22 | +- Auto-build files as you edit by running `$ yarn start` |
| 23 | +- Implement your changes and tests to files in the `src/` directory and corresponding test files |
| 24 | +- To run examples, follow their individual directions. Usually this is just `$ yarn && yarn start`. |
| 25 | +- To run examples using your local build, link to the local `react-query` by running `$ yarn link react-query` from the example's directory |
| 26 | +- Document your changes in the appropriate doc page |
| 27 | +- Git stage your required chnages and commit (see below commit guidelines) |
| 28 | +- Submit PR for review |
| 29 | + |
| 30 | +## Commit message conventions |
| 31 | + |
| 32 | +`react-query` is using [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). |
| 33 | + |
| 34 | +We have very precise rules over how our git commit messages can be formatted. This leads to **more readable messages** that are easy to follow when looking through the **project history**. |
| 35 | + |
| 36 | +### Commit Message Format |
| 37 | + |
| 38 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 39 | +format that includes a **type**, a **scope** and a **subject**: |
| 40 | + |
| 41 | +``` |
| 42 | +<type>(<scope>): <subject> |
| 43 | +<BLANK LINE> |
| 44 | +<body> |
| 45 | +<BLANK LINE> |
| 46 | +<footer> |
| 47 | +``` |
| 48 | + |
| 49 | +The **header** is mandatory and the **scope** of the header is optional. |
| 50 | + |
| 51 | +Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools. |
| 52 | + |
| 53 | +### Type |
| 54 | + |
| 55 | +Must be one of the following: |
| 56 | + |
| 57 | +- **feat**: A new feature |
| 58 | +- **fix**: A bug fix |
| 59 | +- **docs**: Documentation only changes |
| 60 | +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing |
| 61 | + semi-colons, etc) |
| 62 | +- **refactor**: A code change that neither fixes a bug nor adds a feature |
| 63 | +- **perf**: A code change that improves performance |
| 64 | +- **test**: Adding missing or correcting existing tests |
| 65 | +- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation |
| 66 | + generation |
| 67 | + |
| 68 | +### Scope |
| 69 | + |
| 70 | +The scope could be anything specifying place of the commit change. For example `useQuery`, `useMutation` etc... |
| 71 | + |
| 72 | +You can use `*` when the change affects more than a single scope. |
| 73 | + |
| 74 | +### Subject |
| 75 | + |
| 76 | +The subject contains succinct description of the change: |
| 77 | + |
| 78 | +- use the imperative, present tense: "change" not "changed" nor "changes" |
| 79 | +- don't capitalize first letter |
| 80 | +- no dot (.) at the end |
| 81 | + |
| 82 | +### Body |
| 83 | + |
| 84 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior. |
| 85 | + |
| 86 | +### Footer |
| 87 | + |
| 88 | +The footer should contain any information about **Breaking Changes** and is also the place to [reference GitHub issues that this commit closes](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue). |
| 89 | + |
| 90 | +**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. |
| 91 | + |
| 92 | +### Example |
| 93 | + |
| 94 | +Here is an example of the release type that will be done based on a commit messages: |
| 95 | + |
| 96 | +| Commit message | Release type | |
| 97 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | |
| 98 | +| `fix(pencil): stop graphite breaking when too much pressure applied` | Patch Release | |
| 99 | +| `feat(pencil): add 'graphiteWidth' option` | ~~Minor~~ Feature Release | |
| 100 | +| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release | |
| 101 | + |
| 102 | +### Revert |
| 103 | + |
| 104 | +If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted. |
| 105 | + |
| 106 | +## Pull requests |
| 107 | + |
| 108 | +Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface. |
| 109 | + |
| 110 | +Use an appropriate commit type. Be especially careful with breaking changes. |
| 111 | + |
| 112 | +## Releases |
| 113 | + |
| 114 | +For each new commit added to `master` with `git push` or by merging a pull request or merging from another branch, a github action is triggered and runs the `semantic-release` command to make a release if there are codebase changes since the last release that affect the package functionalities. |
0 commit comments