chore: automate Chromium => Puppeteer version listing (puppeteer#6558)

Issue: puppeteer#6482

CONTRIBUTING.md

@@ -261,6 +261,8 @@ The following steps are needed to update the Chromium version.
 1. Run `npm run ensure-correct-devtools-protocol-revision`.
    If it fails, update `package.json` with the expected `devtools-protocol` version.
 1. Run `npm run tsc` and `npm install` and ensure that all tests pass. If a test fails, [bisect](#bisecting-upstream-changes) the upstream cause of the failure, and either update the test expectations accordingly (if it was an intended change) or work around the changes in Puppeteer (if it’s not desirable to change Puppeteer’s observable behavior).
+1. Update `versions.js` with the new Chromium-to-Puppeteer version mapping.
+1. Commit and push your changes and open a pull request.
 
 ### Bisecting upstream changes
 
@@ -277,7 +279,6 @@ Releasing to npm consists of the following phases:
 1. Source Code: mark a release.
     1. Run `npm run release` to bump the version number in `package.json` and populate the changelog.
     1. Run `npm run doc` to update the docs accordingly.
-    1. Update the “Releases per Chromium Version” list in [`docs/api.md`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md) to include the new version. Note: only do this when the Chrome revision is different from the previous release.
     1. Send a PR titled `'chore(release): mark vXXX.YYY.ZZZ'` ([example](https://github.com/puppeteer/puppeteer/pull/5078)).
     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)

docs/api.md

@@ -5,7 +5,8 @@
 - Interactive Documentation: https://pptr.dev
 - API Translations: [中文|Chinese](https://zhaoqize.github.io/puppeteer-api-zh_CN/#/)
 - Troubleshooting: [troubleshooting.md](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md)
-- Releases per Chromium Version:
+<!-- GEN:versions-per-release -->
+- Releases per Chromium version:
   * Chromium 87.0.4272.0 - [Puppeteer v5.4.0](https://github.com/puppeteer/puppeteer/blob/v5.4.0/docs/api.md)
   * Chromium 86.0.4240.0 - [Puppeteer v5.3.0](https://github.com/puppeteer/puppeteer/blob/v5.3.0/docs/api.md)
   * Chromium 85.0.4182.0 - [Puppeteer v5.2.1](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md)
@@ -21,7 +22,7 @@
   * Chromium 74.0.3723.0 - [Puppeteer v1.13.0](https://github.com/puppeteer/puppeteer/blob/v1.13.0/docs/api.md)
   * Chromium 73.0.3679.0 - [Puppeteer v1.12.2](https://github.com/puppeteer/puppeteer/blob/v1.12.2/docs/api.md)
   * [All releases](https://github.com/puppeteer/puppeteer/releases)
-
+<!-- GEN:stop -->
 
 ##### Table of Contents
 

utils/doclint/cli.js

@@ -35,6 +35,14 @@ async function run() {
   const messages = [];
   let changedFiles = false;
 
+  if (!VERSION.endsWith('-post')) {
+    const versions = await Source.readFile(
+      path.join(PROJECT_DIR, 'versions.js')
+    );
+    versions.setText(versions.text().replace(`, 'NEXT'],`, `, '${VERSION}'],`));
+    await versions.save();
+  }
+
   // Documentation checks.
   const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
   const contributing = await Source.readFile(

utils/doclint/preprocessor/index.js

@@ -77,6 +77,8 @@ module.exports.runCommands = function (sources, version) {
       newText = generateTableOfContents(
         command.source.text().substring(command.to)
       );
+    else if (command.name === 'versions-per-release')
+      newText = generateVersionsPerRelease();
     if (newText === null)
       messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
     else if (applyCommand(command, newText)) changedSources.add(command.source);
@@ -144,3 +146,20 @@ function generateTableOfContents(mdText) {
     '\n'
   );
 }
+
+const generateVersionsPerRelease = () => {
+  const versionsPerRelease = require('../../../versions.js');
+  const buffer = ['- Releases per Chromium version:'];
+  for (const [chromiumVersion, puppeteerVersion] of versionsPerRelease) {
+    if (puppeteerVersion === 'NEXT') continue;
+    buffer.push(
+      `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://github.com/puppeteer/puppeteer/blob/${puppeteerVersion}/docs/api.md)`
+    );
+  }
+  buffer.push(
+    `  * [All releases](https://github.com/puppeteer/puppeteer/releases)`
+  );
+
+  const output = '\n' + buffer.join('\n') + '\n';
+  return output;
+};

versions.js

@@ -0,0 +1,37 @@
+/**
+ * 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
+ *
+ *     http://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.
+ */
+
+const versionsPerRelease = new Map([
+  // This is a mapping from Chromium version => Puppeteer version.
+  // In Chromium roll patches, use 'NEXT' for the Puppeteer version.
+  ['88.0.4298.0', 'NEXT'],
+  ['87.0.4272.0', 'v5.4.0'],
+  ['86.0.4240.0', 'v5.3.0'],
+  ['85.0.4182.0', 'v5.2.1'],
+  ['84.0.4147.0', 'v5.1.0'],
+  ['83.0.4103.0', 'v3.1.0'],
+  ['81.0.4044.0', 'v3.0.0'],
+  ['80.0.3987.0', 'v2.1.0'],
+  ['79.0.3942.0', 'v2.0.0'],
+  ['78.0.3882.0', 'v1.20.0'],
+  ['77.0.3803.0', 'v1.19.0'],
+  ['76.0.3803.0', 'v1.17.0'],
+  ['75.0.3765.0', 'v1.15.0'],
+  ['74.0.3723.0', 'v1.13.0'],
+  ['73.0.3679.0', 'v1.12.2'],
+]);
+
+module.exports = versionsPerRelease;