| OLD | NEW |
| 1 ## Developer setup instructions | 1 ## Developer instructions |
| 2 | 2 |
| 3 1. `git clone git@github.com:web-animations/web-animations-next.git` | 3 ### Setup |
| 4 |
| 5 1. Fork web-animations/web-animations-js. |
| 6 1. `git clone git@github.com:$GITHUB_USER/web-animations-js.git` |
| 4 1. `git submodule update --init --recursive` (Necessary for running tests.) | 7 1. `git submodule update --init --recursive` (Necessary for running tests.) |
| 5 1. Install [node](https://nodejs.org/en/) and make sure `npm` is in your $PATH | 8 1. Install [node](https://nodejs.org/en/) and make sure `npm` is in your $PATH |
| 6 1. Run `npm install` in the respository to pull in development dependencies. | 9 1. Run `npm install` in the respository to pull in development dependencies. |
| 7 1. Run `npm install -g grunt grunt-cli` to get the build tools for the command l
ine. | 10 1. Run `npm install -g grunt-cli` to get the build tools for the command line. |
| 11 |
| 12 ### Contributing |
| 13 |
| 14 Note that development should occur against the `dev` branch, not `master`. This |
| 15 is the default target for pull requests. |
| 16 |
| 17 1. In your fork of web-animations-js, `git checkout dev` or create a new branch
whose parent is dev. |
| 8 1. Run `grunt` to build the polyfill. | 18 1. Run `grunt` to build the polyfill. |
| 9 1. Run `grunt test` to run polyfill and web-platform-tests tests. | 19 1. Run `grunt test` to run polyfill and web-platform-tests tests. |
| 20 1. Commit changes to your fork. |
| 21 1. Create a pull request from your fork of web-animations-js to |
| 22 [web-animations/web-animations-js/dev](https://github.com/web-animations/web-
animations-js/tree/dev). |
| 23 1. Ensure that you've signed the [Google Contributor License Agreement](https://
cla.developers.google.com/clas). |
| 10 | 24 |
| 11 | 25 |
| 12 ## Debugging tests | 26 ## Debugging tests |
| 13 | 27 |
| 14 You can run the tests in an interactive mode with `grunt debug`. This starts the | 28 You can run the tests in an interactive mode with `grunt debug`. This starts the |
| 15 Karma server once for each polyfill target for each test framework. | 29 Karma server once for each polyfill target for each test framework. |
| 16 Navigate to `http://localhost:9876/debug.html` to open the test runner in your | 30 Navigate to `http://localhost:9876/debug.html` to open the test runner in your |
| 17 browser of choice, all test results appear in the Javascript console. | 31 browser of choice, all test results appear in the Javascript console. |
| 18 Test failures can be accessed via `window.failures` and `window.formattedFailure
s` | 32 Test failures can be accessed via `window.failures` and `window.formattedFailure
s` |
| 19 once the tests have completed. | 33 once the tests have completed. |
| 20 | 34 |
| 21 The polyfill target and tests can be specified as arguments to the `debug` task.
| 35 The polyfill target and tests can be specified as arguments to the `debug` task. |
| 22 Example: `grunt debug:web-animations-next:test/web-platform-tests/web-animations
/animation/pause.html` | 36 Example: `grunt debug:web-animations-next:test/web-platform-tests/web-animations
/animation/pause.html` |
| 23 Multiple test files may be listed with comma separation. Specifying files will o
utput their URL in the command line. | 37 Multiple test files may be listed with comma separation. Specifying files will o
utput their URL in the command line. |
| 24 Example: `http://localhost:9876/base/test/web-platform-tests/web-animations/anim
ation/pause.html` | 38 Example: `http://localhost:9876/base/test/web-platform-tests/web-animations/anim
ation/pause.html` |
| 25 | 39 |
| 26 | 40 |
| 27 ## Design notes | 41 ## Design notes |
| 28 | 42 |
| 29 [Design diagrams](https://drive.google.com/folderview?id=0B9rpPoIDv3vTNlZxOVp6a2
tNa1E&usp=sharing) | 43 [Design diagrams](https://drive.google.com/folderview?id=0B9rpPoIDv3vTNlZxOVp6a2
tNa1E&usp=sharing) |
| 30 | 44 |
| 31 | 45 |
| 32 ## Publishing a release | 46 ## Publishing a release |
| 33 | 47 |
| 34 1. Determine the version number for the release | 48 1. Determine the version number for the release |
| 35 | 49 |
| 36 * Increment the first number and reset others to 0 when there are large brea
king changes | 50 * Increment the first number and reset others to 0 when there are large brea
king changes |
| 37 * Increment the second number and reset the third to 0 when there are signif
icant new, but backwards compatible features | 51 * Increment the second number and reset the third to 0 when there are signif
icant new, but backwards compatible features |
| 38 * Otherwise, increment the third number | 52 * Otherwise, increment the third number |
| 39 | 53 |
| 40 1. Add versioned release notes to `History.md`, for example: | 54 1. Add versioned release notes to `History.md`, for example: |
| 41 | 55 |
| 42 ### 3.13.37 — *November 1, 2001* | 56 ### 3.13.37 — *November 1, 2001* |
| 43 | 57 |
| 44 * Fixed a bug where nothing worked | 58 * Fixed a bug where nothing worked |
| 45 | 59 |
| 46 Use the following to generate a summary of commits, but edit the list to con
tain only | 60 Use the following to generate a summary of commits, but edit the list to con
tain only |
| 47 relevant information. | 61 relevant information. |
| 48 | 62 |
| 49 git log --first-parent `git describe --tags --abbrev=0 web-animations-js
/master`..web-animations-next/master --pretty=format:" * %s" | 63 git log --first-parent `git describe --tags --abbrev=0 master`..dev --pr
etty=format:" * %s" |
| 50 | 64 |
| 51 1. Specify the new version inside `package.json` (for NPM), for example: | 65 1. Specify the new version inside `package.json` (for NPM), for example: |
| 52 | 66 |
| 53 ```js | 67 ```js |
| 54 "version": "3.13.37", | 68 "version": "3.13.37", |
| 55 ``` | 69 ``` |
| 56 | 70 |
| 57 1. Build the polyfill with `npm install && grunt` then update `README.md`'s Bui
ld Target Comparison with the current gzipped sizes. | 71 1. Build the polyfill with `npm install && grunt` then update `docs/experimenta
l.md`'s Build Target Comparison with the current gzipped sizes. |
| 58 | 72 |
| 59 1. Submit both changes to web-animations-next then follow the procedure to push
from web-animations-next to web-animations-js. | 73 1. Commit the above changes to web-animations-js/dev and merge to |
| 74 web-animations-js/master. |
| 75 |
| 76 ```sh |
| 77 git checkout master |
| 78 git merge dev --no-edit --quiet |
| 79 ``` |
| 80 |
| 81 1. Build and commit minified JavaScript files. |
| 82 |
| 83 ```sh |
| 84 npm install |
| 85 grunt |
| 86 # Optional "grunt test" to make sure everything still passes. |
| 87 git add -f *.min.js{,.map} |
| 88 git rm .gitignore |
| 89 git commit -m 'Add build artifacts from '`cat .git/refs/heads/dev` |
| 90 git push HEAD:refs/heads/master |
| 91 ``` |
| 60 | 92 |
| 61 1. Draft a [new release](https://github.com/web-animations/web-animations-js/re
leases) at the | 93 1. Draft a [new release](https://github.com/web-animations/web-animations-js/re
leases) at the |
| 62 commit pushed to web-animations-js in step #4. Copy the release notes from `
History.md` | 94 commit pushed to web-animations-js in step #4. Copy the release notes from `
History.md` |
| 63 added in step #2. | 95 added in step #2. |
| 64 | 96 |
| 65 1. Once you've pushed to web-animations-js, run `npm publish` from that checked-
out folder | 97 1. Once you've pushed to web-animations-js, run `npm publish` from that checked-
out folder |
| 66 | 98 |
| 67 To do this, you'll need to be a collaborator [on the NPM project](https://www
.npmjs.com/package/web-animations-js), or have a collaborator help you. | 99 To do this, you'll need to be a collaborator [on the NPM project](https://www
.npmjs.com/package/web-animations-js), or have a collaborator help you. |
| 68 | 100 |
| 69 1. If there are any breaking changes to the API in this release you must notify
web-animations-changes@googlegroups.com. | 101 1. If there are any breaking changes to the API in this release you must notify
web-animations-changes@googlegroups.com. |
| 70 | 102 |
| 71 Only owners of the group may post to it so you may need to request ownership
or ask someone to post it for you. | 103 Only owners of the group may post to it so you may need to request ownership
or ask someone to post it for you. |
| 72 | 104 |
| 73 ## Pushing from web-animations-next to web-animations-js | |
| 74 | |
| 75 git fetch web-animations-next | |
| 76 git fetch web-animations-js | |
| 77 git checkout web-animations-js/master | |
| 78 git merge web-animations-next/master --no-edit --quiet | |
| 79 npm install | |
| 80 grunt | |
| 81 # Optional "grunt test" to make sure everything still passes. | |
| 82 git add -f *.min.js* | |
| 83 git rm .gitignore | |
| 84 git commit -m 'Add build artifacts from '`cat .git/refs/remotes/web-animatio
ns-next/master` | |
| 85 git push web-animations-js HEAD:refs/heads/master | |
| 86 | |
| 87 ## Testing architecture | 105 ## Testing architecture |
| 88 | 106 |
| 89 This is an overview of what happens when `grunt test` is run. | 107 This is an overview of what happens when `grunt test` is run. |
| 90 | 108 |
| 91 1. Polyfill tests written in mocha and chai are run. | 109 1. Polyfill tests written in mocha and chai are run. |
| 92 1. grunt creates a karma config with mocha and chai adapters. | 110 1. grunt creates a karma config with mocha and chai adapters. |
| 93 1. grunt adds the test/js files as includes to the karma config. | 111 1. grunt adds the test/js files as includes to the karma config. |
| 94 1. grunt starts the karma server with the config and waits for the result. | 112 1. grunt starts the karma server with the config and waits for the result. |
| 95 1. The mocha adaptor runs the included tests and reports the results to karm
a. | 113 1. The mocha adaptor runs the included tests and reports the results to karm
a. |
| 96 1. karma outputs results to the console and returns the final pass/fail resu
lt to grunt. | 114 1. karma outputs results to the console and returns the final pass/fail resu
lt to grunt. |
| 97 1. web-platform-tests/web-animations tests written in testtharness.js are run. | 115 1. web-platform-tests/web-animations tests written in testtharness.js are run. |
| 98 1. grunt creates a karma config with karma-testharness-adaptor.js included. | 116 1. grunt creates a karma config with karma-testharness-adaptor.js included. |
| 99 1. grunt adds the web-platform-tests/web-animations files to the custom test
harnessTests config in the karma config. | 117 1. grunt adds the web-platform-tests/web-animations files to the custom test
harnessTests config in the karma config. |
| 100 1. grunt adds failure expectations to the custom testharnessTests config in
the karma config. | 118 1. grunt adds failure expectations to the custom testharnessTests config in
the karma config. |
| 101 1. grunt starts the karma server with the config and waits for the result. | 119 1. grunt starts the karma server with the config and waits for the result. |
| 102 1. The testharness.js adaptor runs the included tests (ignoring expected fai
lures) and reports the results to karma. | 120 1. The testharness.js adaptor runs the included tests (ignoring expected fai
lures) and reports the results to karma. |
| 103 1. karma outputs results to the console and returns the final pass/fail resu
lt to grunt. | 121 1. karma outputs results to the console and returns the final pass/fail resu
lt to grunt. |
| 104 1. grunt exits successfully if both test runs passed. | 122 1. grunt exits successfully if both test runs passed. |
| 105 | 123 |
| OLD | NEW |