From 8e0e114153003c693fb0cbe0af19aa078ce21d14 Mon Sep 17 00:00:00 2001 From: Robin Malfait Date: Fri, 28 Jan 2022 12:47:34 +0100 Subject: [PATCH] document all scripts --- .github/CONTRIBUTING.md | 87 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 7 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fc2d525..1e050c9 100644 --- a/.github/CONTRIBUTING.md +++ b/.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