Skip to content

Visualize Your Ideas With Code

docs: improve README and CONTRIBUTING (#216)

Jacobc2c23a94cbba
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ff21ea44..1fd5bc9b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,22 +19,23 @@ out the necessary information.
## Proposing a Change
-If you intend to change the public API, or make any non-trivial changes to the
-implementation, make sure to [create an issue][new-feature] first. This will let
-us discuss a proposal before you put significant effort into it. After a
-proposal has been discussed it may receive the [accepted][label-accepted] label
-indicating that it's ready to be implemented.
+If you intend to change the public API, make any non-trivial changes to the
+implementation, or create brand new guides in the documentation, make sure to
+[create an issue][new-feature] first. This will let us discuss a proposal before
+you put significant effort into it. After a proposal has been discussed it may
+receive the [accepted][label-accepted] label indicating that it's ready to be
+implemented.
-If you're only fixing a bug, it's fine to submit a pull request right away
-without creating an issue but make sure it contains a clear and concise
-description of said bug.
+If you're only fixing a bug or a typo, it's fine to submit a pull request right
+away without creating an issue, but make sure it contains a clear and concise
+description of the bug.
## Working on Issues
-Before you start working on an issue make sure that no one is assigned to it.
+Before you start working on an issue make sure that no one has claimed it yet.
Otherwise, you may duplicate other people's efforts. If somebody claims an issue
but doesn't follow up for more than two weeks, it’s fine to take it over, but
-you should still leave a comment. You should also assign yourself to any issue
+you should still leave a comment. You should also leave a comment on any issue
you're working on, to let others know.
## Semantic Versioning
@@ -43,17 +44,21 @@ Motion Canvas follows [semantic versioning][semver].
## Making a Pull Request
-1. Fork the motion-canvas/core repo.
+1. Fork the motion-canvas/motion-canvas repo.
2. In your forked repo, create a new branch for your changes:
```shell
git checkout -b my-fix-branch master
```
3. Update the code.
-4. Commit your changes using a **descriptive commit message** that follows
+4. Commit your changes using a **descriptive commit message** that follows the
[Angular Commit Message Conventions][commit-format].
```shell
git commit --all
```
+ When committing the changes, our git hooks should automatically run Prettier
+ and ESLint for you. If, for some reason, hooks are not supported in your
+ working environement, you can run these tools using `npm run prettier` and
+ `npm run eslint` respectively.
5. Push your branch to GitHub:
```shell
git push origin my-fix-branch
@@ -61,11 +66,28 @@ Motion Canvas follows [semantic versioning][semver].
6. In GitHub, send a pull request to [the main branch][main] and **request a
review** from [aarthificial](https://github.com/aarthificial).
+### Going through verification
+
+After you made a pull request, a GitHub workflow will be dispatched to verify
+it. There are a few checks that can fail:
+
+- `Commit message` - The commit message doesn't follow the [Angular Commit
+ Message Conventions][commit-format]. You can ignore this check since
+ maintainers can modify your commit message before merging, but make sure to
+ follow the conventions in the future.
+- `Lint` - ESLint has failed. Run `npm run eslint` locally to list the problems.
+- `Tests` - Unit tests have failed. Run `npm run core:test` to check which tests
+ fail and why.
+- `Build` - The build process have failed. There are three possible points of
+ failure you need to check:
+ - `run: npx lerna run build` - Building all packages.
+ - `run: npm run examples:build` - Building the examples.
+ - `run: npm run e2e:test` - Running the end-to-end tests.
+
### Addressing review feedback
1. Make required updates to the code.
-2. Rerun prettier and eslint.
-3. Create a fixup commit and push it to your GitHub repo:
+2. Create a fixup commit and push it to your GitHub repo:
```shell
git commit --all --fixup HEAD
git push
diff --git a/README.md b/README.md
index 12da2732..17fda370 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,33 @@
-# Motion Canvas Core
+<br/>
+<p align="center">
+ <a href="https://motion-canvas.github.io">
+ <img width="180" src="https://motion-canvas.github.io/img/logo_dark.svg" alt="Vite logo">
+ </a>
+</p>
+<p align="center">
+ <a href="https://lerna.js.org"><img src="https://img.shields.io/badge/published%20with-lerna-c084fc?style=flat" alt="published with lerna"></a>
+ <a href="https://vitejs.dev"><img src="https://img.shields.io/badge/powered%20by-vite-646cff?style=flat" alt="powered by lerna"></a>
+ <a href="https://www.npmjs.com/package/@motion-canvas/core"><img src="https://img.shields.io/npm/v/@motion-canvas/core?style=flat" alt="npm package version"></a>
+ <a href="https://discord.gg/XnnWTrHYAW"><img src="https://img.shields.io/discord/1071029581009657896?style=flat&logo=discord&logoColor=fff&color=404eed" alt="discord"></a>
+</p>
+<br/>
-[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
+# Motion Canvas
+
+Motion Canvas is two things:
+
+- A TypeScript library that uses generators to program animations.
+- An editor providing a real-time preview of said animations.
+
+It's a specialized tool designed to create informative vector animations and
+synchronize them with voice-overs.
+
+Aside from providing the preview, the editor allows you to edit certain aspects
+of the animation which could otherwise be tedious.
## Using Motion Canvas
-Check out the [getting started][docs] guide to learn how to use Motion Canvas.
+Check out our [getting started][docs] guide to learn how to use Motion Canvas.
## Developing Motion Canvas locally
@@ -24,7 +47,8 @@ The project is maintained as one monorepo containing the following packages:
| `vite-plugin` | A plugin for Vite used for developing and bundling animations. |
After cloning the repo, run `npm install` in the root of the project to install
-all necessary dependencies.
+all necessary dependencies. Then run `npx lerna run build` to build all the
+packages.
### Developing Core & 2D
diff --git a/packages/docs/docs/intro.md b/packages/docs/docs/intro.md
index aaf51dba..06c541bf 100644
--- a/packages/docs/docs/intro.md
+++ b/packages/docs/docs/intro.md
@@ -7,15 +7,15 @@ slug: /
Motion Canvas consists of two main components:
-- A TypeScript library used to program animations.
+- A TypeScript library that uses generators to program animations.
- An editor providing a real-time preview of said animations.
It's a specialized tool designed to create informative vector animations and
synchronize them with voice-overs. It's not meant to be a replacement for
traditional video editing software.
-Aside from providing a preview, the editor allows you to edit certain aspects of
-the animation that could otherwise be tedious. You can learn more about this
+Aside from providing the preview, the editor allows you to edit certain aspects
+of the animation which could otherwise be tedious. You can learn more about this
functionality in the [time events](/docs/time-events) section.
Motion Canvas is a free and open source project. You can help making it better