document all scripts

.github/CONTRIBUTING.md

@@ -2,6 +2,14 @@
 
 Thanks for your interest in contributing to Headless UI! Please take a moment to review this document **before submitting a pull request**.
 
+- [Pull requests](#pull-requests)
+- [Monorepo](#monorepo)
+- [Installation](#installation)
+- [Coding standards](#coding-standards)
+- [Running tests](#running-tests)
+- [Running playgrounds](#running-playgrounds)
+- [Scripts summary](#scripts-summary)
+
 ## Pull requests
 
 **Please ask first before starting work on any significant new features.**
@@ -11,21 +19,27 @@ Also make sure that you are making changes to both the `React` and `Vue` version
 
 ## Monorepo
 
-The Headless UI repo is a monorepo using `yarn` workspaces. Note that we are using `yarn` version 1.
+The Headless UI repo is a monorepo using `yarn` workspaces. Note that we are using `yarn` **version 1**.
+
+## Installation
+
+You only require a `yarn install` in the root directory to install everything you need.
+
+```sh
+yarn install
+```
 
 ## Coding standards
 
-Our code formatting rules are defined by TSDX, which uses `eslint` and we also use `prettier`. You can check your code against these standards by running:
+We use `prettier` for making sure that the codebase is formatted consistently.
+To automatically fix any style violations in your code, you can run:
 
 ```sh
 yarn lint
 ```
 
-To automatically fix any style violations in your code, you can run:
-
-```sh
-yarn lint --fix
-```
+**Note**: Whenever you commit, the lint check will run on all staged files.
+**Note**: In CI, we will only check your code, and not write with the formatted files. If you want to just check, then you can either run `yarn lint-check` or `CI=true yarn lint`
 
 ## Running tests
 
@@ -46,3 +60,62 @@ yarn vue test
 ```
 
 Please ensure that the tests are passing when submitting a pull request. If you're adding new features to Headless UI, please include tests.
+
+## Running playgrounds
+
+Currently the `React` playground (located in `packages/playground-react`) is a Next.js app that contains some examples which you can find in the `pages` directory. The `Vue` playground (located in `packages/playground-vue`) is a Vite app that contains some examples which you can find in the `src/components` directory.
+
+You can launch them by running:
+
+```sh
+yarn react playground
+
+# or
+
+yarn vue playground
+```
+
+This will also start the necessary watchers so that you don't have to care about them.
+
+## Scripts summary
+
+Global scripts, and some aliases:
+
+- `yarn install`: install all dependencies for all packages
+- `yarn clean`: this will call all `yarn {package} clean` commands
+- `yarn build`: this will call all `yarn {package} build` commands
+- `yarn lint`: this will `lint` all packages
+- `yarn test`: this will `test` all packages
+  - `yarn test`: run all jest tests
+  - `yarn test --watch`: run all jest tests in interactive mode
+  - `yarn test tabs`: run all jest tests filtered by `tabs`
+  - `yarn test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`
+
+Scripts per package:
+
+- `yarn react`: Prefix to run anything in the `@headlessui/react` package
+  - `yarn react test`: run all jest tests
+  - `yarn react test --watch`: run all jest tests in interactive mode
+  - `yarn react test tabs`: run all jest tests filtered by `tabs`
+  - `yarn react test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`
+  - `yarn react build`: build the final artefacts
+  - `yarn react lint`: validate and fix the react codebase using prettier
+  - `yarn react watch`: start a watcher for the react esm build
+    - **Note**: this will be executed for you when using the `yarn react playground`
+    - **Note**: this is not required for jest. You will probably never need this
+  - `yarn react playground`: (alias) start a development server in the `playground-react` package
+    - **Note**: this will also run `yarn react watch` for you, which means that you only need to execute `yarn react playground`
+  - `yarn react clean`: this will remove `dist` files
+- `yarn vue`: Prefix to run anything in the `@headlessui/vue` package
+  - `yarn vue test`: run all jest tests
+  - `yarn vue test --watch`: run all jest tests in interactive mode
+  - `yarn vue test tabs`: run all jest tests filtered by `tabs`
+  - `yarn vue test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`
+  - `yarn vue build`: build the final artefacts
+  - `yarn vue lint`: validate and fix the vue codebase using prettier
+  - `yarn vue watch`: start a watcher for the vue esm build
+    - **Note**: this will be executed for you when using the `yarn vue playground`
+    - **Note**: this is not required for jest. You will probably never need this
+  - `yarn vue playground`: (alias) start a development server in the `playground-vue` package
+    - **Note**: this will also run `yarn vue watch` for you, which means that you only need to execute `yarn react playground`
+  - `yarn vue clean`: this will remove `dist` files