You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As someone who's new to the project, I read the contributing guide and spotted some things that confused me. Hopefully this patch helps to reduces the confusion for others!
When authoring new API methods, consider the following:
79
+
79
80
- Expose as little information as needed. When in doubt, don’t expose new information.
80
81
- Methods are used in favor of getters/setters.
81
82
- The only exception is namespaces, e.g. `page.keyboard` and `page.coverage`
@@ -123,9 +124,9 @@ To deliver to a different location, use "deliver" option:
123
124
124
125
## Writing Documentation
125
126
126
-
All public API should have a descriptive entry in the [docs/api.md](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md). There's a [documentation linter](https://github.com/GoogleChrome/puppeteer/tree/master/utils/doclint) which makes sure documentation is aligned with the codebase.
127
+
All public API should have a descriptive entry in [`docs/api.md`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md). There's a [documentation linter](https://github.com/GoogleChrome/puppeteer/tree/master/utils/doclint) which makes sure documentation is aligned with the codebase.
127
128
128
-
To run documentation linter, use:
129
+
To run the documentation linter, use:
129
130
130
131
```bash
131
132
npm run doc
@@ -147,7 +148,7 @@ A barrier for introducing new installation dependencies is especially high:
147
148
- Tests should be *hermetic*. Tests should not depend on external services.
148
149
- Tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
149
150
150
-
Puppeteer tests are located in [test/test.js](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
151
+
Puppeteer tests are located in [`test/test.js`](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
151
152
and are written with a [TestRunner](https://github.com/GoogleChrome/puppeteer/tree/master/utils/testrunner) framework.
152
153
Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
153
154
@@ -178,7 +179,7 @@ npm run unit -- --break-on-failure
Every public API method or event should be called at least once in tests. To ensure this, there's a coverage command which tracks calls to public API and reports back if some methods/events were not called.
222
+
Every public API method or event should be called at least once in tests. To ensure this, there's a `coverage` command which tracks calls to public API and reports back if some methods/events were not called.
222
223
223
224
Run coverage:
224
225
@@ -232,42 +233,44 @@ See [Debugging Tips](README.md#debugging-tips) in the readme.
232
233
233
234
# For Project Maintainers
234
235
235
-
## Releasing to NPM
236
+
## Releasing to npm
237
+
238
+
Releasing to npm consists of the following phases:
236
239
237
-
Releasing to NPM consists of 3 phases:
238
240
1. Source Code: mark a release.
239
241
1. Bump `package.json` version following the SEMVER rules and send a PR titled `'chore: mark version vXXX.YYY.ZZZ'` ([example](https://github.com/GoogleChrome/puppeteer/commit/808bf8e5582482a1d849ff22a51e52024810905c)).
240
242
2. Make sure the PR passes **all checks**.
241
243
-**WHY**: there are linters in place that help to avoid unnecessary errors, e.g. [like this](https://github.com/GoogleChrome/puppeteer/pull/2446)
242
244
3. Merge the PR.
243
245
4. Once merged, publish release notes using the "create new tag" option.
244
-
-**NOTE**: tag names are prefixed with `'v'`, e.g. for version `1.4.0` tag is `v1.4.0`.
245
-
2. Publish `puppeteer` to NPM.
246
+
-**NOTE**: tag names are prefixed with `'v'`, e.g. for version `1.4.0`the tag is `v1.4.0`.
247
+
2. Publish `puppeteer` to npm.
246
248
1. On your local machine, pull from [upstream](https://github.com/GoogleChrome/puppeteer) and make sure the last commit is the one just merged.
247
249
2. Run `git status` and make sure there are no untracked files.
248
-
-**WHY**: this is to avoid bundling unnecessary files to NPM package
250
+
-**WHY**: this is to avoid adding unnecessary files to the npm package.
249
251
3. Run [`pkgfiles`](https://www.npmjs.com/package/pkgfiles) to make sure you don't publish anything unnecessary.
250
-
4. Run `npm publish`. This will publish`puppeteer` package.
251
-
3. Publish `puppeteer-core` to NPM.
252
-
1. Run `./utils/prepare_puppeteer_core.js`. The script will change the name inside `package.json` to `puppeteer-core`.
253
-
2. Run `npm publish`. This will publish`puppeteer-core` package.
252
+
4. Run `npm publish`. This publishes the`puppeteer` package.
253
+
3. Publish `puppeteer-core` to npm.
254
+
1. Run `./utils/prepare_puppeteer_core.js`. The script changes the name inside `package.json` to `puppeteer-core`.
255
+
2. Run `npm publish`. This publishes the`puppeteer-core` package.
254
256
3. Run `git reset --hard` to reset the changes to `package.json`.
255
257
4. Source Code: mark post-release.
256
258
1. Bump `package.json` version to `-post` version and send a PR titled `'chore: bump version to vXXX.YYY.ZZZ-post'` ([example](https://github.com/GoogleChrome/puppeteer/commit/d02440d1eac98028e29f4e1cf55413062a259156))
257
259
-**NOTE**: make sure to update the "released APIs" section in the top of `docs/api.md`.
258
260
-**NOTE**: no other commits should be landed in-between release commit and bump commit.
259
261
260
-
## Updating NPM dist tags
262
+
## Updating npm dist tags
263
+
264
+
For both `puppeteer` and `puppeteer-core` we maintain the following npm tags:
261
265
262
-
For both `puppeteer` and `puppeteer-firefox` we maintain the following NPM Tags:
263
-
-`chrome-*` tags, e.g. `chrome-75` and so on. These tags match Puppeteer version that corresponds to the `chrome-*` release.
264
-
-`chrome-stable` tag. This tag points to the Puppeteer version that works with current Chrome stable.
266
+
-`chrome-*` tags, e.g. `chrome-75` and so on. These tags match the Puppeteer version that corresponds to the `chrome-*` release.
267
+
-`chrome-stable` tag. This tag points to the Puppeteer version that works with the current Chrome stable release.
265
268
266
269
These tags are updated on every Puppeteer release.
267
270
268
271
> **NOTE**: due to Chrome's rolling release, we take [omahaproxy's linux stable version](https://omahaproxy.appspot.com/) as *stable*.
0 commit comments