CONTRIBUTING.md

Developer instructions

Setup

1. Fork web-animations/web-animations-js.
2. git clone git@github.com:$GITHUB_USER/web-animations-js.git
3. git submodule update --init --recursive (Necessary for running tests.)
4. Install node and make sure npm is in your $PATH
5. Run npm install in the respository to pull in development dependencies.
6. Run npm install -g grunt-cli to get the build tools for the command line.

Contributing

Note that development should occur against the dev branch, not master. This is the default target for pull requests.

1. In your fork of web-animations-js, git checkout dev or create a new branch whose parent is dev.
2. Run grunt to build the polyfill.
3. Run grunt test to run polyfill and web-platform-tests tests.
4. Commit changes to your fork.
5. Create a pull request from your fork of web-animations-js to web-animations/web-animations-js/dev.
6. Ensure that you've signed the Google Contributor License Agreement.

Debugging tests

You can run the tests in an interactive mode with grunt debug. This starts the Karma server once for each polyfill target for each test framework. Navigate to http://localhost:9876/debug.html to open the test runner in your browser of choice, all test results appear in the Javascript console. Test failures can be accessed via window.failures and window.formattedFailures once the tests have completed.

The polyfill target and tests can be specified as arguments to the debug task. Example: grunt debug:web-animations-next:test/web-platform-tests/web-animations/animation/pause.html Multiple test files may be listed with comma separation. Specifying files will output their URL in the command line. Example: http://localhost:9876/base/test/web-platform-tests/web-animations/animation/pause.html

Design notes

Design diagrams

Publishing a release

1. Clone a fresh copy of web-animations-js.

2. Make sure you are on the dev branch.

   git checkout dev

3. Determine the version number for the release

   • Increment the first number and reset others to 0 when there are large breaking changes
   • Increment the second number and reset the third to 0 when there are significant new, but backwards compatible features
   • Otherwise, increment the third number

4. Add versioned release notes to History.md, for example:

   ### 3.13.37 — *November 1, 2001*
   
     * Fixed a bug where nothing worked
   

   Use the following to generate a summary of commits, but edit the list to contain only relevant information.

   git log --first-parent `git describe --tags --abbrev=0 master`..dev --pretty=format:"  * %s"
   

5. Specify the new version inside package.json (for NPM), for example:

     "version": "3.13.37",

6. Build the polyfill with npm install && grunt then update docs/experimental.md's Build Target Comparison with the current gzipped sizes.

7. Commit and push the above changes to web-animations-js/dev.

   # Create a commit with above changes
   git push origin dev

8. Merge to local master branch:

   git checkout master
   git merge dev --no-edit --quiet

9. Build and commit minified JavaScript files.

   npm install
   grunt
   # Optional "grunt test" to make sure everything still passes.
   git add -f *.min.js{,.map}
   git rm --ignore-unmatch .gitignore
   git commit -m 'Add build artifacts from '`cat .git/refs/heads/dev`
   git push origin master

10. Draft a new release.

    • For the tag version, put the new version number of this release.
    • For the target, select "master".
    • For the title, look at previous releases for examples.
    • For the description, copy the release notes from History.md added in step #2.

11. Once you've pushed to web-animations-js, run npm publish from that checked-out folder

    To do this, you'll need to be a collaborator on the NPM project, or have a collaborator help you.

12. If there are any breaking changes to the API in this release you must notify web-animations-changes@googlegroups.com.

    Only owners of the group may post to it so you may need to request ownership or ask someone to post it for you.

Testing architecture

This is an overview of what happens when grunt test is run.

1. Polyfill tests written in mocha and chai are run.
   1. grunt creates a karma config with mocha and chai adapters.
   2. grunt adds the test/js files as includes to the karma config.
   3. grunt starts the karma server with the config and waits for the result.
   4. The mocha adaptor runs the included tests and reports the results to karma.
   5. karma outputs results to the console and returns the final pass/fail result to grunt.
2. web-platform-tests/web-animations tests written in testtharness.js are run.
   1. grunt creates a karma config with karma-testharness-adaptor.js included.
   2. grunt adds the web-platform-tests/web-animations files to the custom testharnessTests config in the karma config.
   3. grunt adds failure expectations to the custom testharnessTests config in the karma config.
   4. grunt starts the karma server with the config and waits for the result.
   5. The testharness.js adaptor runs the included tests (ignoring expected failures) and reports the results to karma.
   6. karma outputs results to the console and returns the final pass/fail result to grunt.
3. grunt exits successfully if both test runs passed.