chore: update CONTRIBUTING

joshuaellis · joshuaellis · commit 79804ba668ba · 2026-05-23T09:22:57.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,93 +1,81 @@
 # How to Contribute
 
-1. Clone this repository:
+Thanks for helping out! This guide covers everything you need to get a local checkout running, send a PR, and (if you have publish access) cut a release.
 
-```sh
-git clone https://github.com/pmndrs/react-spring
-cd react-spring
-```
-
-2. Enable Corepack so the pinned pnpm version activates automatically: `corepack enable`. (See `.nvmrc` for the matching Node version.)
-
-3. Install dependencies: `pnpm install`
-
-4. Let's get cooking! 👨🏻‍🍳🥓
-
-## Guidelines
-
-Be sure your commit messages follow this specification: https://www.conventionalcommits.org/en/v1.0.0-beta.4/
-
-### Windows permission errors
-
-Some Windows users may need to [enable developer mode](https://howtogeek.com/292914/what-is-developer-mode-in-windows-10) if experiencing `EPERM: operation not permitted, symlink` with Preconstruct. If this persists, you might be running on an unsupported drive/format. In which case, consider using [Docker](https://docs.docker.com/docker-for-windows).
-
-### Duplicate `react` errors
-
-React 16.8+ has global state to support its "hooks" feature, so you need to ensure only one copy of `react` exists in your program. Otherwise, you'll most likely see [this error](https://reactjs.org/warnings/invalid-hook-call-warning.html). Please try the following solutions, and let us know if it still doesn't work for you.
+## Prerequisites
 
-- **For `create-react-app` users:** Follow this guide: https://github.com/facebook/react/issues/13991#issuecomment-496383268
-
-- **For `webpack` users:** Add an alias to `webpack.config.js` like this:
-
-  ```js
-  alias: {
-    react: path.resolve('node_modules/react'),
-  }
+- **Node**: see `.nvmrc` (`nvm use` or `fnm use` picks it up). `engines.node` is the same version.
+- **pnpm**: pinned via `packageManager` in the root `package.json`. Enable Corepack so the correct version activates automatically:
+  ```sh
+  corepack enable
   ```
 
-- **For `gatsby` users:** Install `gatsby-plugin-alias-imports` and add this to your `gatsby-config.js` module:
-  ```js
-  {
-    resolve: `gatsby-plugin-alias-imports`,
-    options: {
-      alias: {
-        react: path.resolve('node_modules/react'),
-      },
-    },
-  },
-  ```
+## Getting started
 
-# Publishing
+```sh
+git clone https://github.com/pmndrs/react-spring
+cd react-spring
+pnpm install
+pnpm exec playwright install chromium   # one-off, needed for browser-mode Vitest
+```
 
-We use [`changesets`](https://github.com/atlassian/changesets) to publish our package now.
-All our dependencies are fixed using ~ after [1414](https://github.com/pmndrs/react-spring/issues/1414) but luckily changesets will bump them for every minor version we release.
+Now you're cooking. 👨🏻‍🍳🥓
 
-## Simple release
+## Day-to-day commands
 
-You want to release some new features that haven't been released yet:
+| Task                     | Command                                                 |
+| ------------------------ | ------------------------------------------------------- |
+| Watch-build all packages | `pnpm dev`                                              |
+| Run the docs site        | `pnpm docs:dev`                                         |
+| Run the demo hub         | `pnpm demo:dev`                                         |
+| Full test suite          | `pnpm test` (types + unit + e2e)                        |
+| Unit tests (watch)       | `pnpm vitest --project unit`                            |
+| Single test file         | `pnpm vitest run packages/core/src/SpringValue.test.ts` |
+| Type-check               | `pnpm test:ts`                                          |
+| Lint                     | `pnpm lint`                                             |
+| Format                   | `pnpm format`                                           |
 
-```shell
-pnpm changeset
-```
+Vitest aliases `@react-spring/*` to the package source, so unit tests don't need a prior build. Anything outside Vitest (docs, publishing) does — run `pnpm build` first.
 
-Follow the prompt to flag which packages need to update although with `react-spring` we keep all our packages at the same version.
+> **pnpm isolation gotcha**: `node_modules` is non-hoisted. If you hit `Cannot find module 'foo'` after adding an import, add `foo` to the workspace's `package.json` — don't add a hoist rule.
 
-Then you'll run:
+## Sending a PR
 
-```shell
-pnpm vers
-```
+- **Target branch**: `next` (the active line). `main` may exist but isn't the merge base.
+- **Commits**: follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, …). commitlint enforces this on the `commit-msg` hook.
+- **Pre-commit**: `oxfmt --check` runs via husky. If it fails, run `pnpm format` and re-commit.
+- **Keep PRs small and focused** — easier to review, easier to land.
 
-This will update all the packages correctly according to what version you just set with the `add` script & possibly update the deps within those packages.
+## Publishing
 
-Finally:
+(Maintainers only — needs npm publish access.) We use [changesets](https://github.com/changesets/changesets). All packages are version-locked.
 
-```shell
-pnpm release
-```
+### Simple release
 
-This will build the packages, publish them & push the tags to github to signify a new release. Please then update the `releases` on github & the changelog on `react-spring.dev`
+1. Add a changeset describing the change. With `react-spring` we bump every package to the same version, so flag them all:
+   ```sh
+   pnpm changeset
+   ```
+2. Apply the bump (updates package versions and internal deps):
+   ```sh
+   pnpm vers
+   ```
+3. Publish. This cleans, installs, builds, type-checks, runs unit tests, and publishes via changesets:
+   ```sh
+   pnpm release
+   ```
+   Tags are not pushed automatically (`pnpm release` runs `changeset publish --no-git-tag`). After publishing, draft the GitHub release notes manually and update the changelog on `react-spring.dev`.
 
-## Prerelease
+### Prerelease
 
-Everything above applies but you must first run:
+Enter pre-mode first, then follow the simple release flow:
 
-```shell
-pnpm changeset pre enter beta | alpha | next
+```sh
+pnpm changeset pre enter beta   # or alpha, next
 ```
 
-If you find you're stuck in a prerelease and trying to do a Simple Release, try running:
+If you're stuck in pre-mode and need a normal release:
 
-```shell
+```sh
 pnpm changeset pre exit
 ```
diff --git a/demo/CONTRIBUTING.md b/demo/CONTRIBUTING.md
@@ -1,42 +1,46 @@
 # Contributing a new demo
 
-## Preface
+Thanks for the interest! Before reading on, have a look at the repo's [contribution guide](../CONTRIBUTING.md).
 
-Thanks for being interested in contributing a demo! Before you read more, have you read the [contribution guide](https://github.com/pmndrs/react-spring/blob/main/CONTRIBUTING.md) for the repo? If not, give it a look first!
+## What's required
 
-## What is required
+Demos are based on the CodeSandbox `react-typescript` template. You can either copy an existing demo and tweak it, or build one in CodeSandbox and export the code into `demo/src/sandboxes/<your-demo>/`.
 
-All our demos are based on codesandbox templates for react-typescript. If you're going to contribute a
-demo, you can either copy an existing demo and tweak it or create a new one in codesandbox, export the
-code and add it to the repo.
-
-You should ensure your demo follows the same structure as the other ones:
+Each demo follows this structure:
 
 ```
-- public
-- src
-- - App.tsx
-- - index.tsx
-- .pretterrc
-- package.json
-- tsconfig.json // I would copy this from an existing one
-- thumbnail.png
+demo/src/sandboxes/<your-demo>/
+├── public/
+│   └── index.html
+├── src/
+│   ├── App.tsx        # entry point — imported by the demo hub
+│   └── index.tsx
+├── package.json
+├── thumbnail.png      # 16:9, shown on the website
+└── tsconfig.json      # copy from an existing demo
 ```
 
-This is the minimum we require as the `App.tsx` is used to integrate with our demo hub via vite in the repo.
+`App.tsx` is the entry the demo hub renders via Vite, so it must export a default component.
+
+### `package.json`
 
-A few other things to remember
+- Set a clear `name` and `description` — both surface on the website.
+- List the react-spring hooks you used in `keywords`.
 
 ### Thumbnail
 
-This should be included to showcase your work best! Make sure it's a 16:9 ratio.
+A 16:9 PNG saved as `thumbnail.png` next to `package.json`. Make it count — this is what people see first.
+
+## Running it locally
 
-### Package.json
+From the repo root:
+
+```sh
+pnpm demo:dev
+```
 
-Ensure there's a clear name and description as these appear on the website. You should also use `tags` to highlight keywords
-especially the `react-spring` hooks you've used.
+This serves the demo hub via Vite and picks up your new sandbox automatically.
 
-## When you're ready
+## Opening the PR
 
-When you've finished adding your code, open a PR explaining the example, why you think it should be included
-and most importantly, include a sandbox link so it can be looked at and admired!
+Include a CodeSandbox link, a short explanation of the demo, and why it belongs in the hub.
