mirror of
https://github.com/puppeteer/puppeteer
synced 2024-06-14 14:02:48 +00:00
docs(CONTRIBUTING.md): fix some typos (#4917)
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!
This commit is contained in:
parent
c2651c2b5c
commit
97ff359b0e
@ -12,8 +12,8 @@
|
|||||||
* [Public API Coverage](#public-api-coverage)
|
* [Public API Coverage](#public-api-coverage)
|
||||||
* [Debugging Puppeteer](#debugging-puppeteer)
|
* [Debugging Puppeteer](#debugging-puppeteer)
|
||||||
- [For Project Maintainers](#for-project-maintainers)
|
- [For Project Maintainers](#for-project-maintainers)
|
||||||
* [Releasing to NPM](#releasing-to-npm)
|
* [Releasing to npm](#releasing-to-npm)
|
||||||
* [Updating NPM dist tags](#updating-npm-dist-tags)
|
* [Updating npm dist tags](#updating-npm-dist-tags)
|
||||||
<!-- gen:stop -->
|
<!-- gen:stop -->
|
||||||
|
|
||||||
# How to Contribute
|
# How to Contribute
|
||||||
@ -76,6 +76,7 @@ npm run lint
|
|||||||
## API guidelines
|
## API guidelines
|
||||||
|
|
||||||
When authoring new API methods, consider the following:
|
When authoring new API methods, consider the following:
|
||||||
|
|
||||||
- Expose as little information as needed. When in doubt, don’t expose new information.
|
- Expose as little information as needed. When in doubt, don’t expose new information.
|
||||||
- Methods are used in favor of getters/setters.
|
- Methods are used in favor of getters/setters.
|
||||||
- The only exception is namespaces, e.g. `page.keyboard` and `page.coverage`
|
- 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:
|
|||||||
|
|
||||||
## Writing Documentation
|
## Writing Documentation
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
To run documentation linter, use:
|
To run the documentation linter, use:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run doc
|
npm run doc
|
||||||
@ -147,7 +148,7 @@ A barrier for introducing new installation dependencies is especially high:
|
|||||||
- Tests should be *hermetic*. Tests should not depend on external services.
|
- Tests should be *hermetic*. Tests should not depend on external services.
|
||||||
- Tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
|
- Tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
|
||||||
|
|
||||||
Puppeteer tests are located in [test/test.js](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
|
Puppeteer tests are located in [`test/test.js`](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
|
||||||
and are written with a [TestRunner](https://github.com/GoogleChrome/puppeteer/tree/master/utils/testrunner) framework.
|
and are written with a [TestRunner](https://github.com/GoogleChrome/puppeteer/tree/master/utils/testrunner) framework.
|
||||||
Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
|
Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
|
||||||
|
|
||||||
@ -178,7 +179,7 @@ npm run unit -- --break-on-failure
|
|||||||
fit('should work', async function({server, page}) {
|
fit('should work', async function({server, page}) {
|
||||||
const response = await page.goto(server.EMPTY_PAGE);
|
const response = await page.goto(server.EMPTY_PAGE);
|
||||||
expect(response.ok).toBe(true);
|
expect(response.ok).toBe(true);
|
||||||
})
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
- To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '*cross it*'):
|
- To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '*cross it*'):
|
||||||
@ -189,7 +190,7 @@ npm run unit -- --break-on-failure
|
|||||||
xit('should work', async function({server, page}) {
|
xit('should work', async function({server, page}) {
|
||||||
const response = await page.goto(server.EMPTY_PAGE);
|
const response = await page.goto(server.EMPTY_PAGE);
|
||||||
expect(response.ok).toBe(true);
|
expect(response.ok).toBe(true);
|
||||||
})
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
- To run tests in non-headless mode:
|
- To run tests in non-headless mode:
|
||||||
@ -218,7 +219,7 @@ node --inspect-brk test/test.js
|
|||||||
|
|
||||||
## Public API Coverage
|
## Public API Coverage
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
Run coverage:
|
Run coverage:
|
||||||
|
|
||||||
@ -232,42 +233,44 @@ See [Debugging Tips](README.md#debugging-tips) in the readme.
|
|||||||
|
|
||||||
# For Project Maintainers
|
# For Project Maintainers
|
||||||
|
|
||||||
## Releasing to NPM
|
## Releasing to npm
|
||||||
|
|
||||||
|
Releasing to npm consists of the following phases:
|
||||||
|
|
||||||
Releasing to NPM consists of 3 phases:
|
|
||||||
1. Source Code: mark a release.
|
1. Source Code: mark a release.
|
||||||
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)).
|
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)).
|
||||||
2. Make sure the PR passes **all checks**.
|
2. Make sure the PR passes **all checks**.
|
||||||
- **WHY**: there are linters in place that help to avoid unnecessary errors, e.g. [like this](https://github.com/GoogleChrome/puppeteer/pull/2446)
|
- **WHY**: there are linters in place that help to avoid unnecessary errors, e.g. [like this](https://github.com/GoogleChrome/puppeteer/pull/2446)
|
||||||
3. Merge the PR.
|
3. Merge the PR.
|
||||||
4. Once merged, publish release notes using the "create new tag" option.
|
4. Once merged, publish release notes using the "create new tag" option.
|
||||||
- **NOTE**: tag names are prefixed with `'v'`, e.g. for version `1.4.0` tag is `v1.4.0`.
|
- **NOTE**: tag names are prefixed with `'v'`, e.g. for version `1.4.0` the tag is `v1.4.0`.
|
||||||
2. Publish `puppeteer` to NPM.
|
2. Publish `puppeteer` to npm.
|
||||||
1. On your local machine, pull from [upstream](https://github.com/GoogleChrome/puppeteer) and make sure the last commit is the one just merged.
|
1. On your local machine, pull from [upstream](https://github.com/GoogleChrome/puppeteer) and make sure the last commit is the one just merged.
|
||||||
2. Run `git status` and make sure there are no untracked files.
|
2. Run `git status` and make sure there are no untracked files.
|
||||||
- **WHY**: this is to avoid bundling unnecessary files to NPM package
|
- **WHY**: this is to avoid adding unnecessary files to the npm package.
|
||||||
3. Run [`pkgfiles`](https://www.npmjs.com/package/pkgfiles) to make sure you don't publish anything unnecessary.
|
3. Run [`pkgfiles`](https://www.npmjs.com/package/pkgfiles) to make sure you don't publish anything unnecessary.
|
||||||
4. Run `npm publish`. This will publish `puppeteer` package.
|
4. Run `npm publish`. This publishes the `puppeteer` package.
|
||||||
3. Publish `puppeteer-core` to NPM.
|
3. Publish `puppeteer-core` to npm.
|
||||||
1. Run `./utils/prepare_puppeteer_core.js`. The script will change the name inside `package.json` to `puppeteer-core`.
|
1. Run `./utils/prepare_puppeteer_core.js`. The script changes the name inside `package.json` to `puppeteer-core`.
|
||||||
2. Run `npm publish`. This will publish `puppeteer-core` package.
|
2. Run `npm publish`. This publishes the `puppeteer-core` package.
|
||||||
3. Run `git reset --hard` to reset the changes to `package.json`.
|
3. Run `git reset --hard` to reset the changes to `package.json`.
|
||||||
4. Source Code: mark post-release.
|
4. Source Code: mark post-release.
|
||||||
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))
|
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))
|
||||||
- **NOTE**: make sure to update the "released APIs" section in the top of `docs/api.md`.
|
- **NOTE**: make sure to update the "released APIs" section in the top of `docs/api.md`.
|
||||||
- **NOTE**: no other commits should be landed in-between release commit and bump commit.
|
- **NOTE**: no other commits should be landed in-between release commit and bump commit.
|
||||||
|
|
||||||
## Updating NPM dist tags
|
## Updating npm dist tags
|
||||||
|
|
||||||
For both `puppeteer` and `puppeteer-firefox` we maintain the following NPM Tags:
|
For both `puppeteer` and `puppeteer-core` we maintain the following npm tags:
|
||||||
- `chrome-*` tags, e.g. `chrome-75` and so on. These tags match Puppeteer version that corresponds to the `chrome-*` release.
|
|
||||||
- `chrome-stable` tag. This tag points to the Puppeteer version that works with current Chrome stable.
|
- `chrome-*` tags, e.g. `chrome-75` and so on. These tags match the Puppeteer version that corresponds to the `chrome-*` release.
|
||||||
|
- `chrome-stable` tag. This tag points to the Puppeteer version that works with the current Chrome stable release.
|
||||||
|
|
||||||
These tags are updated on every Puppeteer release.
|
These tags are updated on every Puppeteer release.
|
||||||
|
|
||||||
> **NOTE**: due to Chrome's rolling release, we take [omahaproxy's linux stable version](https://omahaproxy.appspot.com/) as *stable*.
|
> **NOTE**: due to Chrome's rolling release, we take [omahaproxy's linux stable version](https://omahaproxy.appspot.com/) as *stable*.
|
||||||
|
|
||||||
Manging tags 101:
|
Managing tags 101:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# list tags
|
# list tags
|
||||||
|
Loading…
Reference in New Issue
Block a user