mirror of
https://github.com/puppeteer/puppeteer
synced 2024-06-14 14:02:48 +00:00
docs(documentation) capitalize and end sentences (#2537)
This commit is contained in:
Matej Plavevski
Andrey Lushnikov
parent
1c4a8f0bbb
commit
de82b87cfa
@ -39,9 +39,9 @@ information on using pull requests.
|
||||
|
||||
## Code Style
|
||||
|
||||
- coding style is fully defined in [.eslintrc](https://github.com/GoogleChrome/puppeteer/blob/master/.eslintrc.js)
|
||||
- code should be annotated with [closure annotations](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler)
|
||||
- comments should be generally avoided. If the code would not be understood without comments, consider re-writing the code to make it self-explanatory
|
||||
- Coding style is fully defined in [.eslintrc](https://github.com/GoogleChrome/puppeteer/blob/master/.eslintrc.js)
|
||||
- Code should be annotated with [closure annotations](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler).
|
||||
- Comments should be generally avoided. If the code would not be understood without comments, consider re-writing the code to make it self-explanatory.
|
||||
|
||||
To run code linter, use:
|
||||
|
||||
@ -52,11 +52,11 @@ npm run lint
|
||||
## API guidelines
|
||||
|
||||
When authoring new API methods, consider the following:
|
||||
- expose as little information as needed. When in doubt, don’t expose new information
|
||||
- methods are used in favor of getters/setters
|
||||
- the only exception is namespaces, e.g. `page.keyboard` and `page.coverage`
|
||||
- all string literals must be small case. This includes event names and option values
|
||||
- avoid adding "sugar" API (API that is trivially implementable in user-space) unless they're **very** demanded
|
||||
- Expose as little information as needed. When in doubt, don’t expose new information.
|
||||
- Methods are used in favor of getters/setters.
|
||||
- The only exception is namespaces, e.g. `page.keyboard` and `page.coverage`
|
||||
- All string literals must be small case. This includes event names and option values.
|
||||
- Avoid adding "sugar" API (API that is trivially implementable in user-space) unless they're **very** demanded.
|
||||
|
||||
## Commit Messages
|
||||
|
||||
@ -71,16 +71,16 @@ footer
|
||||
```
|
||||
|
||||
1. *label* is one of the following:
|
||||
- `fix` - puppeteer bug fixes
|
||||
- `feat` - puppeteer features
|
||||
- `docs` - changes to docs, e.g. `docs(api.md): ..` to change documentation
|
||||
- `test` - changes to puppeteer tests infrastructure
|
||||
- `style` - puppeteer code style: spaces/alignment/wrapping etc
|
||||
- `chore` - build-related work, e.g. doclint changes / travis / appveyor
|
||||
2. *namespace* is put in parenthesis after label and is optional
|
||||
3. *title* is a brief summary of changes
|
||||
4. *description* is **optional**, new-line separated from title and is in present tense
|
||||
5. *footer* is **optional**, new-line separated from *description* and contains "fixes" / "references" attribution to github issues
|
||||
- `fix` - puppeteer bug fixes.
|
||||
- `feat` - puppeteer features.
|
||||
- `docs` - changes to docs, e.g. `docs(api.md): ..` to change documentation.
|
||||
- `test` - changes to puppeteer tests infrastructure.
|
||||
- `style` - puppeteer code style: spaces/alignment/wrapping etc.
|
||||
- `chore` - build-related work, e.g. doclint changes / travis / appveyor.
|
||||
2. *namespace* is put in parenthesis after label and is optional.
|
||||
3. *title* is a brief summary of changes.
|
||||
4. *description* is **optional**, new-line separated from title and is in present tense.
|
||||
5. *footer* is **optional**, new-line separated from *description* and contains "fixes" / "references" attribution to github issues.
|
||||
6. *footer* should also include "BREAKING CHANGE" if current API clients will break due to this change. It should explain what changed and how to get the old behavior.
|
||||
|
||||
Example:
|
||||
@ -101,7 +101,7 @@ To deliver to a different location, use "deliver" option:
|
||||
|
||||
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.
|
||||
|
||||
To run documentation linter, use
|
||||
To run documentation linter, use:
|
||||
|
||||
```bash
|
||||
npm run doc
|
||||
@ -110,18 +110,18 @@ npm run doc
|
||||
## Adding New Dependencies
|
||||
|
||||
For all dependencies (both installation and development):
|
||||
- **Do not add** a dependency if the desired functionality is easily implementable
|
||||
- if adding a dependency, it should be well-maintained and trustworthy
|
||||
- **Do not add** a dependency if the desired functionality is easily implementable.
|
||||
- If adding a dependency, it should be well-maintained and trustworthy.
|
||||
|
||||
A barrier for introducing new installation dependencies is especially high:
|
||||
- **Do not add** installation dependency unless it's critical to project success
|
||||
- **Do not add** installation dependency unless it's critical to project success.
|
||||
|
||||
## Writing Tests
|
||||
|
||||
- every feature should be accompanied by a test
|
||||
- every public api event/method should be accompanied by a test
|
||||
- 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.
|
||||
- Every feature should be accompanied by a test.
|
||||
- Every public api event/method should be accompanied by a test.
|
||||
- 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.
|
||||
|
||||
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.
|
||||
@ -203,4 +203,4 @@ npm run coverage
|
||||
|
||||
## Debugging Puppeteer
|
||||
|
||||
See [Debugging Tips](README.md#debugging-tips) in the readme
|
||||
See [Debugging Tips](README.md#debugging-tips) in the readme.
|
||||
|
||||
@ -85,9 +85,9 @@ xorg-x11-fonts-misc
|
||||
|
||||
## Chrome Headless fails due to sandbox issues
|
||||
|
||||
- make sure kernel version is up-to-date
|
||||
- read about linux sandbox here: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md
|
||||
- try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)
|
||||
- Make sure kernel version is up-to-date.
|
||||
- Read about linux sandbox here: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md
|
||||
- Try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)
|
||||
|
||||
```js
|
||||
const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
|
||||
|
||||
@ -49,7 +49,7 @@
|
||||
"cross-env": "^5.0.5",
|
||||
"eslint": "^4.0.0",
|
||||
"esprima": "^4.0.0",
|
||||
"markdown-toc": "^1.1.0",
|
||||
"markdown-toc": "^1.2.0",
|
||||
"minimist": "^1.2.0",
|
||||
"ncp": "^2.0.0",
|
||||
"pdfjs-dist": "^1.8.595",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user