Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

CONTRIBUTING.md

238 lines9.5 KB

1# Contributing
2​
3## Questions
4​
5If you have questions about implementation details, help or support, then please use our dedicated community forum at [GitHub Discussions](https://github.com/TanStack/form/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​
9If you have found what you think is a bug, please [file an issue](https://github.com/TanStack/form/issues/new/choose). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [GitHub Discussions](https://github.com/TanStack/form/discussions)
10​
11## Suggesting new features
12​
13If 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​
17If 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
21​
22 ```bash
23 pnpm install
24 ```
25​
26 - We use [pnpm](https://pnpm.io/) for package management - please make sure to use the version mentioned in `package.json`
27​
28 ```bash
29 corepack enable && corepack prepare
30 ```
31​
32 - We use [nvm](https://github.com/nvm-sh/nvm) to manage node versions - please make sure to use the version mentioned in `.nvmrc`
33​
34 ```bash
35 nvm use
36 ```
37​
38- Build all packages.
39​
40 ```bash
41 pnpm build:all
42 ```
43​
44- Run development server.
45​
46 ```bash
47 pnpm run watch
48 ```
49​
50- Implement your changes and tests to files in the `src/` directory and corresponding test files.
51- Document your changes in the appropriate doc page.
52- Git stage your required changes and commit (see below commit guidelines).
53- Submit PR for review.
54​
55### Editing the docs locally and previewing the changes
56​
57The documentations for all the TanStack projects are hosted on [tanstack.com](https://tanstack.com), which is a TanStack Start application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/form` docs.
58​
59> [!NOTE]
60> The website fetches the doc pages from GitHub in production, and searches for them at `../form/docs` in development. Your local clone of `TanStack/form` needs to be in the same directory as the local clone of `TansStack/tanstack.com`.
61​
62You can follow these steps to set up the docs for local development:
63​
641. Make a new directory called `tanstack`.
65​
66```sh
67mkdir tanstack
68```
69​
702. Enter that directory and clone the [`TanStack/form`](https://github.com/TanStack/form) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.
71​
72```sh
73cd tanstack
74git clone git@github.com:TanStack/form.git
75# We probably don't need all the branches and commit history
76# from the `tanstack.com` repo, so let's just create a shallow
77# clone of the latest version of the `main` branch.
78# Read more about shallow clones here:
79# https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#user-content-shallow-clones
80git clone git@github.com:TanStack/tanstack.com.git --depth=1 --single-branch --branch=main
81```
82​
83> [!NOTE]
84> Your `tanstack` directory should look like this:
86> ```
87> tanstack/
88> |
89> +-- form/ (<-- this directory cannot be called anything else!)
90> |
91> +-- tanstack.com/
92> ```
93​
943. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
95​
96```sh
97cd tanstack.com
98pnpm i
99# The app will run on https://localhost:3000 by default
100pnpm dev
101```
102​
1034. Now you can visit http://localhost:3000/form/latest/docs/overview in the browser and see the changes you make in `tanstack/form/docs` there.
104​
105> [!WARNING]
106> You will need to update the `docs/config.json` file (in `TanStack/form`) if you add a new documentation page!
107​
108You can see the whole process in the screen capture below:
109​
110https://github.com/fulopkovacs/form/assets/43729152/9d35a3c3-8153-4e74-9cb2-af275f7a269b
111​
112### Running examples
113​
114- Make sure you've installed the dependencies in the repo's root directory.
115​
116 ```bash
117 pnpm install
118 ```
119​
120- If you want to run the example against your local changes, run below in the repo's root directory. Otherwise, it will be run against the latest TanStack Form release.
121​
122 ```bash
123 pnpm run watch
124 ```
125​
126- Run below in the selected examples' directory.
127​
128 ```bash
129 pnpm run dev
130 ```
131​
132#### Note on standalone execution
133​
134If you want to run an example without installing dependencies for the whole repo, just follow instructions from the example's README.md file. It will be then run against the latest TanStack Form release.
135​
136## Online one-click setup
137​
138You can use Gitpod (An Online Open Source VS Code like IDE which is free for Open Source) for developing online. With a single click it will start a workspace and automatically:
139​
140- clone the `TanStack/form` repo.
141- install all the dependencies in `/` and `/docs`.
142- run below in the root(`/`) to Auto-build files.
143​
144 ```bash
145 npm start
146 ```
147​
148- run below in `/docs`.
149​
150 ```bash
151 npm run dev
152 ```
153​
154[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/TanStack/form)
155​
156## Commit message conventions
157​
158`TanStack/form` is using [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines).
159​
160We 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**.
161​
162### Commit Message Format
163​
164Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
165format that includes a **type**, a **scope** and a **subject**:
166​
167```text
168<type>(<scope>): <subject>
169<BLANK LINE>
170<body>
171<BLANK LINE>
172<footer>
173```
174​
175The **header** is mandatory and the **scope** of the header is optional.
176​
177Any 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.
178​
179### Type
180​
181Must be one of the following:
182​
183- **feat**: A new feature
184- **fix**: A bug fix
185- **docs**: Documentation only changes
186- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
187- **refactor**: A code change that neither fixes a bug nor adds a feature
188- **perf**: A code change that improves performance
189- **test**: Adding missing or correcting existing tests
190- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
191​
192### Scope
193​
194The scope could be anything specifying place of the commit change. For example `form-core`, `react-form` etc...
195​
196You can use `*` when the change affects more than a single scope.
197​
198### Subject
199​
200The subject contains succinct description of the change:
201​
202- use the imperative, present tense: "change" not "changed" nor "changes"
203- don't capitalize first letter
204- no dot (.) at the end
205​
206### Body
207​
208Just 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.
209​
210### Footer
211​
212The 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).
213​
214**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.
215​
216### Example
217​
218Here is an example of the release type that will be done based on a commit messages:
219​
220| Commit message | Release type |
221| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
222| fix(pencil): stop graphite breaking when too much pressure applied | Patch Release |
223| feat(pencil): add `graphiteWidth` option | ~~Minor~~ Feature Release |
224| 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 |
225​
226### Revert
227​
228If 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.
229​
230## Pull requests
231​
232Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface.
233​
234Use an appropriate commit type. Be especially careful with breaking changes.
235​
236## Releases
237​
238For each new commit added to `main` 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.