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 |