chore(docs): compare PRs against next branch instead of current (#4904)

* chore(docs): compare PRs against next branch instead of current

- fixes token mismatch when deleting dataset
- better message when no changes to documentation

* chore(docs): add next branch to the allow list

.github/workflows/docReport.yml

@@ -5,7 +5,7 @@ on:
   pull_request:
   # Build on commits pushed to branches without a PR if it's in the allowlist
   push:
-    branches: [current]
+    branches: [current, next]
 
 jobs:
   report:
@@ -40,11 +40,11 @@ jobs:
         env:
           NODE_OPTIONS: --max_old_space_size=8192
 
-      - name: Create Docs Report on current
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/current' }}
+      - name: Create Docs Report on current or next
+        if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/current' || github.ref == 'refs/heads/next') }}
         env:
           DOCS_REPORT_TOKEN: ${{ secrets.DOCS_REPORT_DATASET_TOKEN }}
-          DOCS_REPORT_DATASET: production
+          DOCS_REPORT_DATASET: ${{ github.ref == 'refs/heads/current' && 'production' || 'next'}}
         run: yarn docs:report:create
 
       - name: Create Docs Report on PR

.github/workflows/docReportTeardown.yml

@@ -35,6 +35,6 @@ jobs:
 
       - name: Remove datasets for closed PRs
         env:
-          DOCS_REPORT_TOKEN: ${{ secrets.PERF_TEST_SANITY_TOKEN }}
+          DOCS_REPORT_TOKEN: ${{ secrets.DOCS_REPORT_DATASET_TOKEN }}
           DOCS_REPORT_DATASET: ${{ github.ref_name }}
         run: yarn docs:report:cleanup

scripts/doc-report/docReport.ts

@@ -35,7 +35,7 @@ interface TransformResult {
 }
 
 const studioMetricsClient = createDocClient(readEnv('DOCS_REPORT_DATASET'))
-const studioMetricsClientProduction = createDocClient('production')
+const studioMetricsClientProduction = createDocClient('next')
 
 function getDocumentationReport(symbols: ExportSymbol[]): Report[] {
   const obj = groupBy(symbols, 'package')
@@ -92,52 +92,60 @@ combineLatest([
     }),
   )
   .subscribe(async (res) => {
-    // convert the result to a markdown table with heading
-    const table = `
-| Package | Documentation Change |
-| ------- | ----------------- |
-${res
-  .sort((a, b) => b.documentedChange - a.documentedChange)
-  .filter((r) => r.documentedChange !== 0)
-  .map(
-    (r) =>
-      `| ${r.package} | ${
-        r.documentedChange > 0 ? `+${r.documentedChange}` : r.documentedChange
-      }% |`,
-  )
-  .join('\n')}
-
-<details>
-  <summary>Full Report</summary>
-  ${res
-    .sort((a, b) => b.documentedChange - a.documentedChange)
-    .map(
-      (r) =>
-        `<details>
-  <summary>${r.package}</summary>
-  <table>
-    <tr>
-      <th>This branch</th>
-      <th>Current release</th>
-    </tr>
-    <tr>
-      <td>${r.branchDocumented} documented</td>
-      <td>${r.prodDocumented} documented</td>
-    </tr>
-    <tr>
-      <td>${r.branchNotDocumented} not documented</td>
-      <td>${r.prodNotDocumented} not documented</td>
-    </tr>
-  </table>
-</details>
-`,
-    )
-    .join('\n')}
-</details>
-`
+    const result = res.filter((r) => r.documentedChange !== 0)
+
+    let report = ''
+
+    if (result.length === 0) {
+      report = 'No changes to documentation'
+    } else {
+      // convert the result to a markdown table with heading
+      report = `
+      | Package | Documentation Change |
+      | ------- | ----------------- |
+      ${res
+        .sort((a, b) => b.documentedChange - a.documentedChange)
+        .filter((r) => r.documentedChange !== 0)
+        .map(
+          (r) =>
+            `| ${r.package} | ${
+              r.documentedChange > 0 ? `+${r.documentedChange}` : r.documentedChange
+            }% |`,
+        )
+        .join('\n')}
+
+      <details>
+        <summary>Full Report</summary>
+        ${res
+          .sort((a, b) => b.documentedChange - a.documentedChange)
+          .map(
+            (r) =>
+              `<details>
+        <summary>${r.package}</summary>
+        <table>
+          <tr>
+            <th>This branch</th>
+            <th>Next branch</th>
+          </tr>
+          <tr>
+            <td>${r.branchDocumented} documented</td>
+            <td>${r.prodDocumented} documented</td>
+          </tr>
+          <tr>
+            <td>${r.branchNotDocumented} not documented</td>
+            <td>${r.prodNotDocumented} not documented</td>
+          </tr>
+        </table>
+      </details>
+      `,
+          )
+          .join('\n')}
+      </details>
+      `
+    }
 
     // save it to a file
-    await fs.writeFile(path.resolve(path.join(__dirname, '..', 'docs-report.md')), table, 'utf8')
+    await fs.writeFile(path.resolve(path.join(__dirname, '..', 'docs-report.md')), report, 'utf8')
 
     timer.end()
   })

scripts/doc-report/docReportCleanup.ts

@@ -15,5 +15,5 @@ studioMetricsClient.datasets
     }
   })
   .catch((err) => {
-    console.error(`Something went wrong! ${err?.response?.body?.message}`)
+    throw new Error(`Something went wrong! ${err?.response?.body?.message}`)
   })