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

CONTRIBUTING.md

168 lines6.1 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/virtual/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/virtual/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/virtual/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/) v9 for package management (run in case of pnpm-related issues).
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/virtual` docs.
58​
59> [!NOTE]
60> The website fetches the doc pages from GitHub in production, and searches for them at `../config/docs` in development. Your local clone of `TanStack/virtual` 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/virtual`](https://github.com/TanStack/virtual) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.
71​
72```sh
73cd tanstack
74git clone git@github.com:TanStack/virtual.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> +-- virtual/ (<-- 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/virtual/latest/docs/overview in the browser and see the changes you make in `TanStack/virtual/docs` there.
104​
105> [!WARNING]
106> You will need to update the `docs/config.json` file (in `TanStack/config`) 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 Virtual 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 Virtual 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/virtual` 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/virtual)
155​
156## Changesets
157​
158This repo uses [Changesets](https://github.com/changesets/changesets) to automate releases. If your PR should release a new package version (patch, minor, or major), please run run `pnpm changeset` and commit the file. If needed, changeset descriptions can be more descriptive, and will be included in the changelog. If your PR affects docs, examples, styles, etc., you probably don't need to generate a changeset.
159​
160## Pull requests
161​
162Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface.
163​
164Use an appropriate commit type. Be especially careful with breaking changes.
165​
166## Releases
167​
168For each new commit added to `main`, a GitHub Workflow is triggered which runs the [Changesets Action](https://github.com/changesets/action). This generates a preview PR showing the impact of all changesets. When this PR is merged, the package will be published to NPM.