From d111d19f788d88d984dcf4ad7542f59acd2f4c1e Mon Sep 17 00:00:00 2001 From: jrandolf <101637635+jrandolf@users.noreply.github.com> Date: Mon, 30 May 2022 21:50:34 +0200 Subject: [PATCH] fix: process documentation during publishing (#8433) --- .github/release-please.yml | 1 - .github/workflows/publish.yml | 60 +++++++++---------- .husky/pre-push | 2 +- .prettierignore | 1 + .versionrc.js | 27 --------- CONTRIBUTING.md | 15 +---- README.md | 22 +++---- package.json | 2 +- release-please-config.json | 1 - .../js-cjs-import-esm-output/package.json | 3 - .../js-esm-import-cjs-output/package.json | 3 - .../js-esm-import-esm-output/package.json | 3 - .../ts-cjs-import-cjs-output/package.json | 3 - .../ts-esm-import-cjs-output/package.json | 3 - .../ts-esm-import-esm-output/package.json | 3 - utils/doclint/cli.js | 13 +++- utils/doclint/preprocessor/index.js | 54 ++++++++++------- .../doclint/preprocessor/preprocessor.spec.js | 59 +++++++----------- 18 files changed, 107 insertions(+), 168 deletions(-) delete mode 100644 .versionrc.js diff --git a/.github/release-please.yml b/.github/release-please.yml index 6d782c662bea8..7230cee90c66f 100644 --- a/.github/release-please.yml +++ b/.github/release-please.yml @@ -1,4 +1,3 @@ releaseType: node -handleGHRelease: true primaryBranch: main manifest: true diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 02f8dc6ce56fe..4da1bf37bbbe7 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -3,10 +3,36 @@ name: Publish on: push: tags: - - '*' + - v* jobs: + pre-publish: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: main + - name: Install dependencies + run: npm install + - name: Build + run: | + node utils/generate_version_file.js + IS_PRE_RELEASE=1 npm run doc + - name: Configure git + run: | + git config --global user.name 'actions-bot' + git config --global user.email '' + - name: Commit and push + run: | + git add -A + git commit -m "chore: freeze current version in code" + git push + publish: + needs: pre-publish runs-on: ubuntu-latest permissions: contents: read @@ -17,6 +43,8 @@ jobs: run: npm install - name: Build puppeteer run: npm run build + - name: Generate release documentation + run: IS_RELEASE=1 npm run doc - name: Publish puppeteer env: NPM_TOKEN: ${{secrets.NPM_TOKEN_PUPPETEER}} @@ -36,33 +64,3 @@ jobs: npm config set registry 'https://wombat-dressing-room.appspot.com/' npm config set '//wombat-dressing-room.appspot.com/:_authToken' '${NPM_TOKEN}' npm publish - - post-publish: - needs: publish - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - ref: main - - name: Append `-post` to version - id: post-version - run: | - npm version --no-git-tag-version --no-commit-hooks "$(jq -r .version ./package.json)-post" - echo ::set-output name=VERSION::$(jq -r .version ./package.json) - - name: Build - run: | - npm install - npm run build - npm run doc - - name: Configure git - run: | - git config --global user.name 'actions-bot' - git config --global user.email '' - - name: Commit and push - run: | - git add -A - git commit -m "chore: bump version to ${{ steps.post-version.outputs.VERSION }}" - git push diff --git a/.husky/pre-push b/.husky/pre-push index 62434f4dcb242..71fac926e75e0 100755 --- a/.husky/pre-push +++ b/.husky/pre-push @@ -1,4 +1,4 @@ #!/bin/sh . "$(dirname "$0")/_/husky.sh" -npm run tsc && npm run eslint && npm run doc && npm run ensure-pinned-deps +npm run tsc && npm run eslint && npm run doc && npm run prettier && npm run ensure-pinned-deps diff --git a/.prettierignore b/.prettierignore index 657f2d23bccff..91dde1356f1fb 100644 --- a/.prettierignore +++ b/.prettierignore @@ -14,3 +14,4 @@ CHANGELOG.md test/assets/ /.local-chromium/ /.local-firefox/ +test-ts-types diff --git a/.versionrc.js b/.versionrc.js deleted file mode 100644 index bb311a2085dfc..0000000000000 --- a/.versionrc.js +++ /dev/null @@ -1,27 +0,0 @@ -/** - * Copyright 2020 Google Inc. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -module.exports = { - releaseCommitMessageFormat: 'chore(release): mark v{{currentTag}}', - skip: { - tag: true, - }, - scripts: { - prerelease: 'node utils/remove_version_suffix.js', - postbump: - 'node utils/generate_version_file.js && IS_RELEASE=true npm run doc && git add --update', - }, -}; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4f18061394b3..162872110e741 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -312,17 +312,4 @@ By default, it will use the Chromium revision in `src/revisions.ts` from the `ma ## Releasing to npm -Releasing to npm consists of the following phases: - -1. Source Code: mark a release. - 1. Run `npm run release`. (This automatically bumps the version number in `package.json`, populates the changelog, updates the docs, and creates a Git commit for the next step.) - 1. Send a PR for the commit created in the previous step. - 1. 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/puppeteer/puppeteer/pull/2446) - 1. Merge the PR. - 1. Once merged, publish the release notes from `CHANGELOG.md` using [GitHub’s “draft new release tag” option](https://github.com/puppeteer/puppeteer/releases/new). - - **NOTE**: tag names are prefixed with `'v'`, e.g. for version `1.4.0` the tag is `v1.4.0`. - 1. As soon as the Git tag is created by completing the previous step, our CI automatically `npm publish`es the new releases for both the `puppeteer` and `puppeteer-core` packages. -1. Source Code: mark post-release. - 1. Bump `package.json` version to the `-post` version, run `npm run doc` to update the “released APIs” section at the top of `docs/api.md` accordingly, and send a PR titled `'chore: bump version to vXXX.YYY.ZZZ-post'` ([example](https://github.com/puppeteer/puppeteer/pull/6808)) - - **NOTE**: no other commits should be landed in-between release commit and bump commit. +We use [release-please](https://github.com/googleapis/release-please) to automate releases. When a release should be done, check for the release PR in our [pull requests](https://github.com/puppeteer/puppeteer/pulls) and merge it. diff --git a/README.md b/README.md index c9a369db6273d..9addf61a477ea 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ -###### [API](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/puppeteer/puppeteer/blob/main/CONTRIBUTING.md) | [Troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md) +###### [API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/puppeteer/puppeteer/blob/main/CONTRIBUTING.md) | [Troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md) > Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). Puppeteer runs [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) by default, but can be configured to run full (non-headless) Chrome or Chromium. @@ -39,7 +39,7 @@ npm i puppeteer # or "yarn add puppeteer" ``` -Note: When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, download into another path, or download a different browser, see [Environment variables](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#environment-variables). +Note: When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, download into another path, or download a different browser, see [Environment variables](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#environment-variables). ### puppeteer-core @@ -63,7 +63,7 @@ Note: Prior to v1.18.1, Puppeteer required at least Node v6.4.0. Versions from v Node 8.9.0+. Starting from v3.0.0 Puppeteer starts to rely on Node 10.18.1+. All examples below use async/await which is only supported in Node v7.6.0 or greater. Puppeteer will be familiar to people using other browser testing frameworks. You create an instance -of `Browser`, open pages, and then manipulate them with [Puppeteer's API](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#). +of `Browser`, open pages, and then manipulate them with [Puppeteer's API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#). **Example** - navigating to https://example.com and saving a screenshot as _example.png_: @@ -88,7 +88,7 @@ Execute script on the command line node example.js ``` -Puppeteer sets an initial page size to 800×600px, which defines the screenshot size. The page size can be customized with [`Page.setViewport()`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#pagesetviewportviewport). +Puppeteer sets an initial page size to 800×600px, which defines the screenshot size. The page size can be customized with [`Page.setViewport()`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagesetviewportviewport). **Example** - create a PDF. @@ -115,7 +115,7 @@ Execute script on the command line node hn.js ``` -See [`Page.pdf()`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#pagepdfoptions) for more information about creating pdfs. +See [`Page.pdf()`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagepdfoptions) for more information about creating pdfs. **Example** - evaluate script in the context of the page @@ -150,7 +150,7 @@ Execute script on the command line node get-dimensions.js ``` -See [`Page.evaluate()`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#pageevaluatepagefunction-args) for more information on `evaluate` and related methods like `evaluateOnNewDocument` and `exposeFunction`. +See [`Page.evaluate()`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pageevaluatepagefunction-args) for more information on `evaluate` and related methods like `evaluateOnNewDocument` and `exposeFunction`. @@ -160,7 +160,7 @@ See [`Page.evaluate()`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs **1. Uses Headless mode** -Puppeteer launches Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). To launch a full version of Chromium, set the [`headless` option](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#puppeteerlaunchoptions) when launching a browser: +Puppeteer launches Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). To launch a full version of Chromium, set the [`headless` option](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#puppeteerlaunchoptions) when launching a browser: ```js const browser = await puppeteer.launch({ headless: false }); // default is true @@ -176,7 +176,7 @@ pass in the executable's path when creating a `Browser` instance: const browser = await puppeteer.launch({ executablePath: '/path/to/Chrome' }); ``` -You can also use Puppeteer with Firefox Nightly (experimental support). See [`Puppeteer.launch()`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#puppeteerlaunchoptions) for more information. +You can also use Puppeteer with Firefox Nightly (experimental support). See [`Puppeteer.launch()`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#puppeteerlaunchoptions) for more information. See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. @@ -188,7 +188,7 @@ Puppeteer creates its own browser user profile which it **cleans up on every run ## Resources -- [API Documentation](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md) +- [API Documentation](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md) - [Examples](https://github.com/puppeteer/puppeteer/tree/main/examples/) - [Community list of Puppeteer resources](https://github.com/transitive-bullshit/awesome-puppeteer) @@ -330,7 +330,7 @@ See [Contributing](https://github.com/puppeteer/puppeteer/blob/main/CONTRIBUTING Official Firefox support is currently experimental. The ongoing collaboration with Mozilla aims to support common end-to-end testing use cases, for which developers expect cross-browser coverage. The Puppeteer team needs input from users to stabilize Firefox support and to bring missing APIs to our attention. -From Puppeteer v2.1.0 onwards you can specify [`puppeteer.launch({product: 'firefox'})`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#puppeteerlaunchoptions) to run your Puppeteer scripts in Firefox Nightly, without any additional custom patches. While [an older experiment](https://www.npmjs.com/package/puppeteer-firefox) required a patched version of Firefox, [the current approach](https://wiki.mozilla.org/Remote) works with “stock” Firefox. +From Puppeteer v2.1.0 onwards you can specify [`puppeteer.launch({product: 'firefox'})`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#puppeteerlaunchoptions) to run your Puppeteer scripts in Firefox Nightly, without any additional custom patches. While [an older experiment](https://www.npmjs.com/package/puppeteer-firefox) required a patched version of Firefox, [the current approach](https://wiki.mozilla.org/Remote) works with “stock” Firefox. We will continue to collaborate with other browser vendors to bring Puppeteer support to browsers such as Safari. This effort includes exploration of a standard for executing cross-browser commands (instead of relying on the non-standard DevTools Protocol used by Chrome). @@ -433,7 +433,7 @@ await page.evaluate(() => { You may find that Puppeteer does not behave as expected when controlling pages that incorporate audio and video. (For example, [video playback/screenshots is likely to fail](https://github.com/puppeteer/puppeteer/issues/291).) There are two reasons for this: -- Puppeteer is bundled with Chromium — not Chrome — and so by default, it inherits all of [Chromium's media-related limitations](https://www.chromium.org/audio-video). This means that Puppeteer does not support licensed formats such as AAC or H.264. (However, it is possible to force Puppeteer to use a separately-installed version Chrome instead of Chromium via the [`executablePath` option to `puppeteer.launch`](https://github.com/puppeteer/puppeteer/blob/v14.1.1/docs/api.md#puppeteerlaunchoptions). You should only use this configuration if you need an official release of Chrome that supports these media formats.) +- Puppeteer is bundled with Chromium — not Chrome — and so by default, it inherits all of [Chromium's media-related limitations](https://www.chromium.org/audio-video). This means that Puppeteer does not support licensed formats such as AAC or H.264. (However, it is possible to force Puppeteer to use a separately-installed version Chrome instead of Chromium via the [`executablePath` option to `puppeteer.launch`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#puppeteerlaunchoptions). You should only use this configuration if you need an official release of Chrome that supports these media formats.) - Since Puppeteer (in all configurations) controls a desktop version of Chromium/Chrome, features that are only supported by the mobile version of Chrome are not supported. This means that Puppeteer [does not support HTTP Live Streaming (HLS)](https://caniuse.com/#feat=http-live-streaming). #### Q: I am having trouble installing / running Puppeteer in my test environment. Where should I look for help? diff --git a/package.json b/package.json index 2540038af5960..41d8fc852e1a0 100644 --- a/package.json +++ b/package.json @@ -44,7 +44,7 @@ "commitlint": "commitlint --from=HEAD~1", "prettier": "prettier --check .", "prettier-fix": "prettier --write .", - "lint": "npm run eslint && npm run build && npm run doc && npm run prettier", + "lint": "npm run build && npm run eslint && npm run doc && npm run prettier", "doc": "node utils/doclint/cli.js", "generate-api-docs-for-testing": "commonmark docs/api.md > docs/api.html", "clean-lib": "rimraf lib", diff --git a/release-please-config.json b/release-please-config.json index 90334b74bade8..c0181386980a4 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -1,5 +1,4 @@ { - "last-release-sha": "d4321e53c909c7ecf90f5f27d3a136cba176f40b", "packages": { ".": { "releaseType": "node", diff --git a/test-ts-types/js-cjs-import-esm-output/package.json b/test-ts-types/js-cjs-import-esm-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/js-cjs-import-esm-output/package.json +++ b/test-ts-types/js-cjs-import-esm-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/test-ts-types/js-esm-import-cjs-output/package.json b/test-ts-types/js-esm-import-cjs-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/js-esm-import-cjs-output/package.json +++ b/test-ts-types/js-esm-import-cjs-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/test-ts-types/js-esm-import-esm-output/package.json b/test-ts-types/js-esm-import-esm-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/js-esm-import-esm-output/package.json +++ b/test-ts-types/js-esm-import-esm-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/test-ts-types/ts-cjs-import-cjs-output/package.json b/test-ts-types/ts-cjs-import-cjs-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/ts-cjs-import-cjs-output/package.json +++ b/test-ts-types/ts-cjs-import-cjs-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/test-ts-types/ts-esm-import-cjs-output/package.json b/test-ts-types/ts-esm-import-cjs-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/ts-esm-import-cjs-output/package.json +++ b/test-ts-types/ts-esm-import-cjs-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/test-ts-types/ts-esm-import-esm-output/package.json b/test-ts-types/ts-esm-import-esm-output/package.json index d2aa4f9434afd..6141e954b0d5a 100644 --- a/test-ts-types/ts-esm-import-esm-output/package.json +++ b/test-ts-types/ts-esm-import-esm-output/package.json @@ -6,9 +6,6 @@ "scripts": { "compile": "../../node_modules/.bin/tsc" }, - "devDependencies": { - "typescript": "4.2.4" - }, "dependencies": { "puppeteer": "file:../../puppeteer.tgz" } diff --git a/utils/doclint/cli.js b/utils/doclint/cli.js index a6c07af68d9a8..91de816fa3454 100755 --- a/utils/doclint/cli.js +++ b/utils/doclint/cli.js @@ -29,6 +29,7 @@ const YELLOW_COLOR = '\x1b[33m'; const RESET_COLOR = '\x1b[0m'; const IS_RELEASE = Boolean(process.env.IS_RELEASE); +const IS_PRE_RELEASE = Boolean(process.env.IS_PRE_RELEASE); run(); @@ -39,7 +40,7 @@ async function run() { const messages = []; let changedFiles = false; - if (IS_RELEASE) { + if (IS_RELEASE || IS_PRE_RELEASE) { const versions = await Source.readFile( path.join(PROJECT_DIR, 'versions.js') ); @@ -61,9 +62,15 @@ async function run() { const mdSources = [readme, api, troubleshooting, contributing]; const preprocessor = require('./preprocessor/index.js'); - messages.push(...(await preprocessor.runCommands(mdSources, VERSION))); messages.push( - ...(await preprocessor.ensureReleasedAPILinks([readme], VERSION)) + ...(await preprocessor.runCommands(mdSources, VERSION, IS_RELEASE)) + ); + messages.push( + ...(await preprocessor.ensureReleasedAPILinks( + [readme], + VERSION, + IS_RELEASE + )) ); const browser = await puppeteer.launch(); diff --git a/utils/doclint/preprocessor/index.js b/utils/doclint/preprocessor/index.js index 3cdd808b236e9..f57986535b09a 100644 --- a/utils/doclint/preprocessor/index.js +++ b/utils/doclint/preprocessor/index.js @@ -16,14 +16,16 @@ const Message = require('../Message.js'); -const IS_RELEASE = Boolean(process.env.IS_RELEASE); - -module.exports.ensureReleasedAPILinks = function (sources, version) { +module.exports.ensureReleasedAPILinks = function ( + sources, + version, + isReleaseVersion +) { // Release version is everything that doesn't include "-". const apiLinkRegex = - /https:\/\/github.com\/puppeteer\/puppeteer\/blob\/v[^/]*\/docs\/api.md/gi; - const lastReleasedAPI = `https://github.com/puppeteer/puppeteer/blob/v${ - version.split('-')[0] + /https:\/\/github.com\/puppeteer\/puppeteer\/blob\/[^/]*\/docs\/api.md/gi; + const lastReleasedAPI = `https://github.com/puppeteer/puppeteer/blob/${ + isReleaseVersion ? `v${version}` : 'main' }/docs/api.md`; const messages = []; @@ -36,10 +38,7 @@ module.exports.ensureReleasedAPILinks = function (sources, version) { return messages; }; -module.exports.runCommands = function (sources, version) { - // Release version is everything that doesn't include "-". - const isReleaseVersion = IS_RELEASE || !version.includes('-'); - +module.exports.runCommands = function (sources, version, isReleaseVersion) { const messages = []; const commands = []; for (const source of sources) { @@ -72,22 +71,31 @@ module.exports.runCommands = function (sources, version) { commands.sort((a, b) => b.from - a.from); for (const command of commands) { let newText = null; - if (command.name === 'version') - newText = isReleaseVersion ? `v${version}` : 'Tip-Of-Tree'; - else if (command.name === 'empty-if-release') - newText = isReleaseVersion ? '' : command.originalText; - else if (command.name === 'toc') - newText = generateTableOfContents( - command.source.text().substring(command.to) - ); - else if (command.name === 'versions-per-release') - newText = generateVersionsPerRelease(); - if (newText === null) + switch (command.name) { + case 'version': + newText = isReleaseVersion ? `v${version}` : 'Tip-Of-Tree'; + break; + case 'empty-if-release': + newText = isReleaseVersion ? '' : command.originalText; + break; + case 'toc': + newText = generateTableOfContents( + command.source.text().substring(command.to) + ); + break; + case 'versions-per-release': + newText = generateVersionsPerRelease(); + break; + } + if (newText === null) { messages.push(Message.error(`Unknown command 'gen:${command.name}'`)); - else if (applyCommand(command, newText)) changedSources.add(command.source); + } else if (applyCommand(command, newText)) { + changedSources.add(command.source); + } } - for (const source of changedSources) + for (const source of changedSources) { messages.push(Message.info(`GEN: updated ${source.projectPath()}`)); + } return messages; }; diff --git a/utils/doclint/preprocessor/preprocessor.spec.js b/utils/doclint/preprocessor/preprocessor.spec.js index 86625e7d1c982..d01e01d4c83a5 100644 --- a/utils/doclint/preprocessor/preprocessor.spec.js +++ b/utils/doclint/preprocessor/preprocessor.spec.js @@ -20,21 +20,6 @@ const expect = require('expect'); describe('doclint preprocessor specs', function () { describe('ensureReleasedAPILinks', function () { - it('should work with non-release version', function () { - const source = new Source( - 'doc.md', - ` - [API](https://github.com/puppeteer/puppeteer/blob/v1.1.0/docs/api.md#class-page) - ` - ); - const messages = ensureReleasedAPILinks([source], '1.3.0-post'); - expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); - expect(messages[0].text).toContain('doc.md'); - expect(source.text()).toBe(` - [API](https://github.com/puppeteer/puppeteer/blob/v1.3.0/docs/api.md#class-page) - `); - }); it('should work with release version', function () { const source = new Source( 'doc.md', @@ -42,22 +27,22 @@ describe('doclint preprocessor specs', function () { [API](https://github.com/puppeteer/puppeteer/blob/v1.1.0/docs/api.md#class-page) ` ); - const messages = ensureReleasedAPILinks([source], '1.3.0'); + const messages = ensureReleasedAPILinks([source], '1.3.0', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` [API](https://github.com/puppeteer/puppeteer/blob/v1.3.0/docs/api.md#class-page) `); }); - it('should keep main branch links intact', function () { + it('should keep main branch links intact on non-release', function () { const source = new Source( 'doc.md', ` [API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-page) ` ); - const messages = ensureReleasedAPILinks([source], '1.3.0'); + const messages = ensureReleasedAPILinks([source], '1.3.0', false); expect(messages.length).toBe(0); expect(source.text()).toBe(` [API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-page) @@ -73,7 +58,7 @@ describe('doclint preprocessor specs', function () { something ` ); - const messages = runCommands([source], '1.1.1'); + const messages = runCommands([source], '1.1.1', true); expect(source.hasUpdatedText()).toBe(false); expect(messages.length).toBe(1); expect(messages[0].type).toBe('error'); @@ -87,9 +72,9 @@ describe('doclint preprocessor specs', function () { Puppeteer XXX ` ); - const messages = runCommands([source], '1.2.0'); + const messages = runCommands([source], '1.2.0', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` Puppeteer v1.2.0 @@ -102,9 +87,9 @@ describe('doclint preprocessor specs', function () { Puppeteer XXX ` ); - const messages = runCommands([source], '1.2.0-post'); + const messages = runCommands([source], '1.2.0', false); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` Puppeteer Tip-Of-Tree @@ -116,14 +101,14 @@ describe('doclint preprocessor specs', function () { `Puppeteer vWHAT ` ); - runCommands([source], '1.1.1'); + runCommands([source], '1.1.1', true); expect(source.text()).toBe( `Puppeteer vv1.1.1` ); }); it('should not tolerate missing gen:stop', function () { const source = new Source('doc.md', ``); - const messages = runCommands([source], '1.2.0'); + const messages = runCommands([source], '1.2.0', true); expect(source.hasUpdatedText()).toBe(false); expect(messages.length).toBe(1); expect(messages[0].type).toBe('error'); @@ -138,9 +123,9 @@ describe('doclint preprocessor specs', function () { XXX ` ); - const messages = runCommands([source], '1.1.1'); + const messages = runCommands([source], '1.1.1', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` @@ -153,7 +138,7 @@ describe('doclint preprocessor specs', function () { XXX ` ); - const messages = runCommands([source], '1.1.1-post'); + const messages = runCommands([source], '1.1.1', false); expect(messages.length).toBe(0); expect(source.text()).toBe(` XXX @@ -169,9 +154,9 @@ describe('doclint preprocessor specs', function () { #### page.$ #### page.$$` ); - const messages = runCommands([source], '1.3.0'); + const messages = runCommands([source], '1.3.0', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` - [class: page](#class-page) @@ -193,9 +178,9 @@ describe('doclint preprocessor specs', function () { \`\`\` ` ); - const messages = runCommands([source], '1.3.0'); + const messages = runCommands([source], '1.3.0', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` - [class: page](#class-page) @@ -214,9 +199,9 @@ describe('doclint preprocessor specs', function () { ### some [link](#foobar) here ` ); - const messages = runCommands([source], '1.3.0'); + const messages = runCommands([source], '1.3.0', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` - [some link here](#some-link-here) @@ -234,9 +219,9 @@ describe('doclint preprocessor specs', function () { ZZZ ` ); - const messages = runCommands([source], '1.1.1'); + const messages = runCommands([source], '1.1.1', true); expect(messages.length).toBe(1); - expect(messages[0].type).toBe('warning'); + expect(messages[0].type).toBe('info'); expect(messages[0].text).toContain('doc.md'); expect(source.text()).toBe(` v1.1.1