theatre/CONTRIBUTING.md

Contributing to Theatre.js

Development workflow

Setting up the environment

Make sure you have node 14+ installed:

$ node -v
> v14.0.0

and yarn 1.22+:

$ yarn -v
> 1.22.10

Then clone the repo:

# for SSH:
$ git clone git@github.com:<github-username>/theatre.git
# for HTTPS:
$ git clone https://github.com/<github-username>/theatre.git

$ cd theatre

And fetch the dependencies with yarn:

$ yarn

• Notes about Yarn:
  • This project uses yarn workspaces so npm install will not work.
  • This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ on your machine, yarn will automatically switch to v2 when you cd into theatre. Read more about Yarn v2 here.

Hacking with playground

The quickest way to start tweaking things is to run the playground package.

$ cd ./packages/playground
$ yarn serve
# or, shortcut:
$ cd root
$ yarn playground

The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js. It also contains the project's end-to-end tests.

Read more at ./packages/playground/README.md.

Hacking with examples/

Other than playground, the examples/ folder contains a few small projects that use Theatre.js with parcel, Create react app, and other build tools. This means that unlike playground, you have to build all the packages before running the examples.

You can do that by running the build command at the root of the repo:

$ yarn build

Then build any of the examples:

$ cd examples/dom-cra
$ yarn start

Running unit/integration tests

We use a single jest setup for the repo. The tests files have the .test.ts or .test.tsx extension.

You can run the tests at the root of the repo:

$ yarn test

# or run them in watch mode:
$ yarn test --watch

Running end-to-end tests

End-to-end tests are hosted in the playground package. More details there.

Type checking

The packages in this repo have full typescript coverage, so you should be able to get diagnostics and intellisense if your editor supports typescript.

You can also run a typecheck of the whole repo from the root:

$ yarn typecheck

# or in watch mode:
$ yarn typecheck --watch

• If you're using VSCode, we have a "Typescript watch" task for VSCode that you can use by running "Run Task -> Typescript watch".
• If you wish to contribute code without typescript annotations, that's totally fine. We're happy to add the annotations to your PR.

Linting

We're using a minimal ESLint setup for linting. If your editor supports ESLint, you should get diagnostics as you code. You can also run the lint command from the root of the repo:

$ yarn lint:all

Some lint rules have autofix, so you can run:

$ yarn lint:all --fix

Publishing to npm

Currently all packages (except for @theatre/r3f) share the same version number. In order to publish to npm, you can run the release script from the root of the repo:

$ yarn release x.y.z # npm publish version x.y.z
$ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev"
$ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc"

Generating API docs

We use API extractor to generate API docs in markdown. We put the markdown files in the theatre-docs repo, which also contains the tutorials and guides.

To generate the API docs, run the build:api-docs from the root of the repo:

$ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api folder and regenerate the markdown files

Learn more about api documentation here.

Project structure

The monorepo consists of:

• @theatre/core – The core animation library at ./theatre/core.
• @theatre/studio – The visual editor at ./theatre/studio.
• @theatre/dataverse – The reactive dataflow library at ./packages/dataverse.
• @theatre/react – Utilities for using Theatre.js with React at ./packages/react.
• @theatre/r3f – The react-three-fiber extension at ./packages/r3f.
• playground – The playground explained above, located at ./packages/playground
• examples/ * A bunch of examples at ./examples.

In addition, each package may contain a dotEnv/ folder that holds some dev-related files, like bundle configuration, lint setup, etc.

Commands

These commands are available at the root workspace:

# Run the playground. It's a shortcut for `cd ./playground; yarn run serve`
$ yarn playground

# Run all the tests.
$ yarn test

# Run tests in watch mode.
$ yarn test --watch

# Typecheck all the packages
$ yarn typecheck

# Typecheck all the packages in watch mode
$ yarn typecheck --watch

# Run eslint on the repo
$ yarn lint:all

# Run eslint and auto fix
$ yarn lint:all --fix

# Build all the packages
$ yarn build

# Build the api documentation
$ yarn build:api-docs /path/to/theatre-docs/docs/api/

Yarn passes all extra parameters to the internal scripts. So, for example, if you wish to run the tests in watch mode, you can run yarn test --watch.

Documentation

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

• Documentation: https://docs.theatrejs.com
• API docs: https://docs.theatrejs.com/api/
• Video: Theatre.js Crash Course

What to contribute

You can contribute with:

• Bug fixes
• Feature suggestions
• Features implementations
• Documentation (or write/record tutorials of your own which we'll showcase)
• Create examples projects for your own particular dev stack (eg. using Pixie/Vue/THREE.js/Babylon/etc)

Another great way to help is to join our community and chime in on questions and share ideas.

Helping with outstanding issues

Feel free to chime in on any issue. We have labeled some with "Help wanted" or "Good first issue" if you're just getting started with the codebase.

Sending pull requests

We use Github's regular PR workflow. Basically fork the repo, push your commits, and send a pull request.

If you're a core contributor and have write access to the repo, you should submit your pull requests from a branch rather than a personal fork. The naming convention for these branches should be:

• (feature|hotfix|docs)/[identifier] or
• an autogenerated branch name from a Github issue (On an issue without a PR, look under the "Development" sidebar heading for a "create a branch link")

Squash & merge should be preferred most of the time to keep the main branch clean, unless the commit history is relevant, in which case rebase should be used.

Always update your feature branch with a rebase from the main branch to make sure that you don't accidentally break main with an undetected conflict.

Branches belonging to merged PRs should be deleted.