From c336d2e397ed7225895ffbeb6a40d62b6f743358 Mon Sep 17 00:00:00 2001 From: Aria Minaei Date: Tue, 5 Oct 2021 13:56:42 +0200 Subject: [PATCH] More contribution docs --- CONTRIBUTING.md | 129 +++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7da4f7..04bf747 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,102 +1,108 @@ # Contributing to Theatre.js -## Getting Started +## The quick version + +Have `node 14+` and `yarn 1.22+` installed. Then `git clone` and `yarn install`. Then `cd packages/playground` and `yarn run serve`. Happy hacking! + +## The long version ### Prerequisites Make sure you have [Node](https://nodejs.org/) installed at v14.0.0+ ```sh -node -v - -v14.0.0 - +$ node -v +> v14.0.0 ``` -and [Yarn](https://classic.yarnpkg.com/en/) at v2.0.0+. +and [Yarn](https://classic.yarnpkg.com/en/) at v1.22.10+. ```sh -yarn -v - -2.0.0 +$ yarn -v +> 1.22.10 ``` +> **Note about Yarn v2**: This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ installed, and `cd` into `/path/to/theatre`, yarn will automatically switch to v2. Read more about Yarn v2 [here](https://yarnpkg.com/). + ### Fork, Clone & Install -Start by forking Theatre.js to your GitHub account. Then clone your fork and -install dependencies: +Start by forking Theatre.js to your GitHub account. Then clone your fork and install dependencies: ```sh -git clone git@github.com:/theatre.git -cd theatre -yarn +$ git clone git@github.com:/theatre.git +$ cd theatre +$ yarn ``` > ⚠ theatre relies on -> [yarn workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) so +> [yarn workspaces](https://yarnpkg.com/features/workspaces) so > `npm install` will not work in this repository. Add our repo as a git remote so you can pull/rebase your fork with our latest updates: +```sh +$ git remote add upstream git@github.com:AriaMinaei/theatre.git ``` -git remote add upstream git@github.com:AriaMinaei/theatre.git + +## Start hacking with `playground` + +The quickest way to start tweaking things is to run the `playground` package. + +```sh +$ cd ./packages/playground +$ yarn serve ``` +The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js. + +It uses a single ESBuild config to build all of the related packages in one go, so you don't have to run a bunch of build commands. + +Read more at [`./packages/playground/README.md`](./packages/playground/README.md). + ## Project structure -> This section is lacking in instructions (PRs welcome!). +* `@theatre/core` – The core animation library. + * Location: [`./theatre/core`](./theatre/core) +* `@theatre/studio` – The visual editor. + * Location: [`./theatre/studio`](./theatre/studio) +* `@theatre/dataverse` – The reactive dataflow library. + * Location: [`./packagtes/dataverse`](./packages/dataverse) +* `@theatre/react` – Utilities for using Theatre with React. + * Location: [`./packagtes/react`](./packages/react) +* `@theatre/r3f` – The react-three-fiber extension. + * Location: [`./packagtes/r3f`](./packages/r3f) +* `playground` – The quickest way to hack on the internals of Theatre. It bundles all the related packages together with one ESBuild setup. + * Location: [`./packagtes/playground`](./packages/playground) +* `examples/` + * A bunch of examples, using Theatre with [parcel](https://parceljs.org) or [Create react app](create-react-app.dev). -### `@theatre/core` - -The core animation library. - -This project is located under [`./theatre/core`](./theatre/core). - -### `@theatre/studio` - -The visual editor. - -This project is located under [`./theatre/studio`](./theatre/studio). ### Commands -> This list is not updated, you should run `yarn run` to see all scripts. - #### Root commands ```sh -yarn playground // run the playground +# Run the playground. It's a shortcut for `cd ./playground; yarn run serve` +yarn playground -yarn test // run all tests -yarn typecheck // TS typechecking +# Run all the tests. +yarn test + +# Run tests in watch mode. +yarn test --watch + +# Typecheck all the packages +yarn typecheck + +# Run eslint on the repo +yarn lint:all + +# Run eslint and auto fix +yarn lint:all --fix ``` -#### Theatre workspace commands - -Commands available for the `@theatre` workspace: - -```sh -yarn build:js -yarn build:js:watch -``` - -## Devflow - -> This section is lacking in instructions (PRs welcome!). - -When working on changes for the `@theatre` workspace, you want to have a couple -of things running concurrently: - -1. Run the playground to verify the changes - ``` - yarn playground - ``` -2. Watch and rebuild theatre packages on changes: - ```sh - cd theatre - yarn build:js - ``` +> Yarn passes all extra parameters to the internal scripts. So, for example, if you wish to run the tests in watch more, you can run `yarn test --watch`. ## Workflow @@ -114,9 +120,7 @@ If you have any questions or issues along the way, drop a message in the > This section is lacking in instructions (PRs welcome!). -The libraries come bundled with typescript definitions with TSDoc (opens new -window)comments. You can explore the API if your editor is configured to display -TSDoc comments. +The libraries come bundled with typescript definitions with TSDoc comments. You can explore the API if your editor is configured to display TSDoc comments. Other references @@ -125,8 +129,7 @@ Other references ## Testing -Run tests during development with `yarn test --watch` to re-run tests on file -changes. +Run tests during development with `yarn test --watch` to re-run tests on file changes. ### Examples