This guide is for people who want to contribute to the library or are curious to learn what’s behind the scenes: how is it tested? what do we automate? how do we do releases? etc.
If you are looking for documentation on how to use the library, the user guide is for you.
NOTE: this document is a work in progress. More content will be added in stages. If you have questions you’d like to see answered, please add them as comments on this issue. THANKS!
In this guide:
Although tween.js does not need node.js to work, we use it for development. So you will need to install node.js before you can work on the library.
Node.js includes the npm tool that we use to run scripts such as the one for packaging, running tests, etc. Please make sure it is working in your system before you attempt to run any of the steps detailed below.
Once node.js is installed, clone the tween.js repository:
git clone https://github.com/tweenjs/tween.js.git
Change to the folder:
cd tween.js
And run the script to install development dependencies:
npm install
Or in three lines:
git clone https://github.com/tweenjs/tween.js.git
cd tween.js
npm install
Once npm install completes successfully, try having a go at running the tests:
npm test
If you get issues running any of the above, try to search for the text of the error using your search engine of choice. This is normally the fastest route, as many people might have encountered the same issue already.
There’s a suite of automated tests in the test directory.
These can quickly spot regressions on the code–useful when new features are added or when code is changed to fix a bug; we don’t want to introduce new bugs! They also spot style issues, which helps us keep the library cohesive.
To run the tests, type:
npm test
You should run the tests after you change code in the library. If you change the behaviour the tests describe, the tests won’t pass and you’ll get an error pointing to the test(s) that failed. This might be either because…
The one that happens more frequently is the first one, but the second one has happened, with edge cases.
Another thing you should do once the automated tests pass is to run the examples in the examples folder. It is rare, but it might happen that your changes introduced cosmetic differences that the automated tests are not checking for, and the only way to notice this is by running the examples and have a human spot the difference in output. If you don’t want to checkout two copies of the library, you can look at the online examples.
Tests are in the src/tests.ts file.
The tests are executed using nodeunit.
TODO: the tests should also work if opening test/unit/nodeunit.html in a browser, but they are broken right now. There is an open issue to make them work again.
We use Prettier and ESLint to ensure the code style is uniform.
To automatically format code and report any errors for pieces of code that aren’t automatically formattable, run:
npm run test-lint
The Prettier rules are in .prettierrc.js and ESLint rules are in .eslintrc.js.
We would like to test for performance regressions i.e. if a change made things go slower, or simply, for performance, so we can compare the performance of the same code between different browsers.
There’s an open issue to track work on this, but we have not made progress on it yet. Help! :-)
We use GitHub Actions for continuous integration so that a build and tests will run for every pull request. The .github/workflows/tests.yml file tells GitHub what to run; in our case we run npm install followed by npm test in the OSes and versions of Node.js specified in that file.
TODO: Add macOS and Windows to OSes that the tests run on. Help! :)
Currently the release process is manual.
When ready to make a release on the master branch, ensure there are no un-committed changes, then run npm run release:patch to release a new version with its patch number bumped, npm run release:minor to release a new version with its minor number bumped, or npm run release:major to release a new version with its major number bumped.
Tip: see semver.org and the npm-semver docs to learn about semantic versioning.