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.gitChange to the folder:
cd tween.jsAnd run the script to install development dependencies:
npm installOr in three lines:
git clone https://github.com/tweenjs/tween.js.git
cd tween.js
npm installOnce npm install completes successfully, try having a go at running the tests:
npm testIf 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 testYou 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...
- you overlooked something or there's an error in your code, or...
- the library or the tests themselves are wrong
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 test/unit/tests.js 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 JSCS and JSHint to ensure the code style is uniform.
This tool helps us spot mostly 'cosmetic' code style issues. For example, white spaces versus tabs, spaces between brackets, etc.
To run it:
npm run test-styleThe rules for JSCS are in test/jscs.json.
This tool helps us spot code quality issues. For example, using the right equality operator, unused variables, etc.
To run it:
npm run test-correctnessThe rules for JSHint are in test/jshintrc.
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 have implemented a continuous integration system that does things automatically for us. It runs the tests automatically each time a pull request is made, and it can also publish new releases automatically in certain cases.
If proposed changes in a pull request break anything, contributors get feedback without having to wait for a human to have a look at the code. Also, the request cannot be merged until the tests pass.
We are using the Travis CI platform to run the tests. You will find a little information area at the bottom of the pull request page, letting you know about the state of the tests.
Example of all checks passing:
And when checks fail:
If a pull request is updated by adding new commits, the tests will run again.
Travis is configured with the .travis.yml file (if you don't see it with your file explorer or the Finder, it's because the file name starts with a dot and so it's hidden--try opening it with the terminal).
We use the semantic-release tool in combination with Travis to automatically create releases on GitHub and publish them to npm.
Each time a pull request is merged, Travis will run the tests. If they pass without errors, Travis will run the after_success step:
after_success:
- npm run semantic-releaseThis in turn will run the semantic-release script in package.json:
"semantic-release": "semantic-release pre && npm publish && semantic-release post"And when the new release is made:
semantic-releasedetermines the next version number- a new entry is added to the GitHub releases list, along with a list of all the commits included in the change, and a ZIP file with that version, for people who want to download ZIPs
- the git commit is tagged with the version number (tools like Bower use tags)
- it is also published to npm, with the new version number in
package.json.
Note: the default configuration option for semantic-release is to run only if the branch name is master. Otherwise, we would be generating lots of pushes and releases, as Travis runs with each pull request!
Please also note that the version number in package.json is intentionally 0.0.0-development, as we do not want to encourage anyone to modify this manually, but we also cannot remove the version field from the file or installing modules using the git repository directly will fail.
Like npm, semantic-release follows the semver convention, so each release is identified by a unique MAJOR.MINOR.PATCH version number. For example, given version 1.2.3: 1 = major, 2 = minor, 3 = patch.
In this system, breaking changes (e.g. the API is modified, and updating to a new version might require updating the code that uses the library) should increase the major number. If there are backwards compatible changes (e.g. a new feature that does not modify existing APIs) the minor number will increase. Smaller changes, such as a documentation update, only increase the patch number.
semantic-release uses the commit messages to decide on the next version number automatically.
This is really great, because keeping track of version numbers or deciding on whether a new release should be a major or minor change is an extremely boring task, best left to machines.
For this to work automatically, the commit messages need to follow a certain syntax:
<type_of_commit>: <commit log message as usual>.
The following table lists the types of commits and their effect on version numbers, using the default behaviour.
| Type of commit | Description | Version increase? |
|---|---|---|
| fix | fixes a bug but does not change the API | Increases PATCH |
| style | formatting changes | |
| docs | adding/removing/changing docs | |
| refactor | rewriting code but not breaking changes, adding features or fixing bugs | |
| test | changes in tests, e.g. adding a missing one) | |
| feat | adding new features which do not change the API | Increases MINOR |
| BREAKING CHANGE | changes the API | Increases MAJOR |
This is mostly for informational purposes, as semantic-release is already configured with Travis and contributors shouldn't need to worry about this, but it is good to document everything.
First install the global cli utility:
npm install -g semantic-release-cliThen in an existing node.js based project (i.e. a package.json already exists):
semantic-release-cli setupIt will ask you a series of questions to set up semantic-release on the project. If all goes well, the next time you push to GitHub, a new release will automatically happen.
You will need to have TravisCI enabled in your account.
Install the module:
npm install --save-dev semantic-releaseEdit package.json to add the semantic-release script:
"scripts": {
//...
"semantic-release": "semantic-release pre && npm publish && semantic-release post"
//...
},Create a .travis.yml file if it doesn't exist yet (here is help creating travis.yml files), or have a look at ours.
Add an after_success section to .travis.yml, in order to run semantic-release:
after_success:
- npm run semantic-releaseNow we need to enable the project in Travis CI, so make sure you have an account there and are logged in.
Enable the project in Travis (if you're the maintainer) or ask the maintainer to enable it, in the Travis settings page.
Click on the cog near to the project name to configure some options.
Scroll down until you see Environment Variables.
Add tokens for GH_TOKEN and NPM_TOKEN. Make sure both variables are hidden: Display value in build log should be Off.
You can get tokens from npm and from GitHub. These allow services such as Travis to act on your behalf, which is why you need to ensure they are not displayed in the build log.
Hopefully, now each time you commit and push to GitHub semantic-release will run (if using the master branch as described above) and maybe a new version will be published.