chore(docs): getting a bot to comment on docs PRs with docs previews (#…

…4600)

This PR makes it substantially easy to review and see changes in PRs
containing docs changes by deploying a preview and commenting on the PR
with a link to that preview.

There are a few changes worth mentioning:
- The deploy/non-deploy logic is moved from the CircleCI config to the
downstream script `deploy_netlify`
- This script will always deploy in prod when PRs are merged, so no
change in logic here.
- But now, the script gets that PR's file changes via the Github API and
checks if there are changes in docs. If there are, then the deploy runs
without the `--prod` flag, which will deploy a preview only
- It then parses the output searching for the Unique URL which is passed
to the bot comment logic
- The bot comment logic is changed so it can be reused, by basically
adding an enum for the different comment markdowns and importing them
dynamically

This way, the deploy only runs in PRs that have changes in docs,
commenting on those PRs with a deploy preview. When merged, changes are
deployed in prod.

.circleci/config.yml

@@ -1118,17 +1118,12 @@ jobs:
             fi
       - run:
           name: "Build docs"
-          command: build docs
-          aztec_manifest_key: docs
-      - run:
-          name: "Deploy docs"
           command: |
-            if [ "$CIRCLE_BRANCH" == "master" ]; then
-              echo "Deploying docs (on master)."
-              docs/deploy_netlify.sh
-            else
-              echo "Skipping doc deploy (not on master)."
-            fi
+            echo "Building docs"
+            build docs
+
+            echo "Deploying docs"
+            docs/deploy_netlify.sh $CIRCLE_BRANCH $CIRCLE_PULL_REQUEST
 
   yellow-paper:
     machine:

docs/deploy_netlify.sh

@@ -5,5 +5,41 @@ set -eu
 extract_repo docs /usr/src extracted-repo
 cd extracted-repo/src/docs
 npm install netlify-cli -g
-netlify deploy --site aztec-docs-dev
-netlify deploy --site aztec-docs-dev --prod
+
+DEPLOY_OUTPUT=""
+
+# Check if we're on master
+if [ "$1" = "master" ]; then
+    # Deploy to production if the argument is "master"
+    DEPLOY_OUTPUT=$(netlify deploy --site aztec-docs-dev --prod)
+else    
+    # TODO we should prob see if check_rebuild can be used for this
+    PR_URL="$2"
+    API_URL="${PR_URL/github.com/api.github.com/repos}"
+    API_URL="${API_URL/pull/pulls}"
+    API_URL="${API_URL}/files"
+
+    echo "API URL: $API_URL"
+
+    DOCS_CHANGED=$(curl -L \
+        -H "Authorization: Bearer $AZTEC_BOT_COMMENTER_GITHUB_TOKEN" \
+        "${API_URL}" | \
+        jq '[.[] | select(.filename | startswith("docs/"))] | length > 0')
+
+    echo "Docs changed: $DOCS_CHANGED"
+
+    if [ "$DOCS_CHANGED" = "false" ]; then
+        echo "No docs changed, not deploying"
+        exit 0
+    fi
+
+    # Regular deploy if the argument is not "master" and docs changed
+    DEPLOY_OUTPUT=$(netlify deploy --site aztec-docs-dev)
+    UNIQUE_DEPLOY_URL=$(echo "$DEPLOY_OUTPUT" | grep -E "https://.*aztec-docs-dev.netlify.app" | awk '{print $4}')
+    echo "Unique deploy URL: $UNIQUE_DEPLOY_URL"
+
+    extract_repo yarn-project /usr/src project
+    cd project/src/yarn-project/scripts
+
+    UNIQUE_DEPLOY_URL=$UNIQUE_DEPLOY_URL yarn docs-preview-comment
+fi

yarn-project/scripts/package.json

@@ -7,7 +7,8 @@
   "bin": {
     "bench-aggregate": "./dest/bin/bench-aggregate.js",
     "bench-comment": "./dest/bin/bench-comment.js",
-    "bench-markdown": "./dest/bin/bench-markdown.js"
+    "bench-markdown": "./dest/bin/bench-markdown.js",
+    "docs-preview-comment": "./dest/bin/docs-preview.js"
   },
   "scripts": {
     "build": "yarn clean && tsc -b",

yarn-project/scripts/run_script.sh

@@ -11,4 +11,4 @@ REPO="yarn-project"
 retry docker pull $(calculate_image_uri $REPO)
 retry docker tag $(calculate_image_uri $REPO) aztecprotocol/$REPO:latest
 
-docker run ${DOCKER_RUN_OPTS:-} --rm aztecprotocol/$REPO:latest $@
+docker run ${DOCKER_RUN_OPTS:-} --rm aztecprotocol/$REPO:latest $@

yarn-project/scripts/src/bin/bench-comment.ts

@@ -1,6 +1,7 @@
-import { main } from '../benchmarks/comment.js';
+import { COMMENT_TYPES } from '../types.js';
+import main from '../utils/comment.js';
 
-void main().catch(err => {
+void main(COMMENT_TYPES.BENCH).catch(err => {
   // eslint-disable-next-line no-console
   console.error(err.message);
   process.exit(1);

yarn-project/scripts/src/bin/docs-preview.ts

@@ -0,0 +1,8 @@
+import { COMMENT_TYPES } from '../types.js';
+import main from '../utils/comment.js';
+
+void main(COMMENT_TYPES.DOCS).catch(err => {
+  // eslint-disable-next-line no-console
+  console.error(err.message);
+  process.exit(1);
+});

yarn-project/scripts/src/docs_previews/markdown.ts

@@ -0,0 +1,15 @@
+const url = process.env.UNIQUE_DEPLOY_URL as string;
+const cleanUrl = (str: string) =>
+  // eslint-disable-next-line no-control-regex
+  str.replace(/[\u001B\u009B][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
+
+const COMMENT_MARK = '<!-- AUTOGENERATED DOCS COMMENT -->';
+
+export function getMarkdown() {
+  return `
+# Docs Preview
+Hey there! 👋 You can check your preview at ${cleanUrl(url)}
+
+${COMMENT_MARK}
+`;
+}

yarn-project/scripts/src/types.ts

@@ -0,0 +1,4 @@
+export enum COMMENT_TYPES {
+  BENCH = '<!-- AUTOGENERATED BENCHMARK COMMENT -->',
+  DOCS = '<!-- AUTOGENERATED DOCS COMMENT -->',
+}

yarn-project/scripts/src/benchmarks/comment.ts → yarn-project/scripts/src/utils/comment.ts

@@ -5,15 +5,24 @@ import { createConsoleLogger } from '@aztec/foundation/log';
 
 import * as https from 'https';
 
-import { getMarkdown } from './markdown.js';
+import { COMMENT_TYPES } from '../types.js';
 
 const GITHUB_TOKEN = process.env.AZTEC_BOT_COMMENTER_GITHUB_TOKEN;
 const OWNER = 'AztecProtocol';
 const REPO = 'aztec3-packages';
-const COMMENT_MARK = '<!-- AUTOGENERATED BENCHMARK COMMENT -->';
 
 const log = createConsoleLogger();
 
+async function getMarkdown(commentType: COMMENT_TYPES) {
+  if (commentType === COMMENT_TYPES.BENCH) {
+    return (await import('../benchmarks/markdown.js')).getMarkdown();
+  } else if (commentType === COMMENT_TYPES.DOCS) {
+    return (await import('../docs_previews/markdown.js')).getMarkdown();
+  } else {
+    throw new Error('Invalid comment type');
+  }
+}
+
 /** Returns the number of the current PR */
 function getPrNumber() {
   if (!process.env.CIRCLE_PULL_REQUEST) {
@@ -24,20 +33,20 @@ function getPrNumber() {
 }
 
 /** Function to check if a bench comment already exists */
-async function getExistingComment() {
+async function getExistingComment(commentType: COMMENT_TYPES) {
   try {
     const response = await sendGitHubRequest(`/repos/${OWNER}/${REPO}/issues/${getPrNumber()}/comments`);
     const comments = JSON.parse(response);
-    return comments.find((comment: any) => comment.body.includes(COMMENT_MARK));
+    return comments.find((comment: any) => comment.body.includes(commentType));
   } catch (error: any) {
     throw new Error('Error checking for existing comments: ' + error.message);
   }
 }
 
 /** Function to create or update a comment */
-async function upsertComment(existingCommentId: string) {
+async function upsertComment(existingCommentId: string, commentType: COMMENT_TYPES) {
   try {
-    const commentContent = getMarkdown();
+    const commentContent = await getMarkdown(commentType);
     const commentData = { body: commentContent };
 
     const requestMethod = existingCommentId ? 'PATCH' : 'POST';
@@ -104,7 +113,7 @@ function sendGitHubRequest(url: string, method = 'GET', data?: object): Promise<
 }
 
 /** Entrypoint */
-export async function main() {
-  const existingComment = await getExistingComment();
-  await upsertComment(existingComment?.id);
+export default async function main(commentType: COMMENT_TYPES = COMMENT_TYPES.BENCH) {
+  const existingComment = await getExistingComment(commentType);
+  await upsertComment(existingComment?.id, commentType);
 }

yarn-project/yarn.lock

@@ -825,6 +825,7 @@ __metadata:
     bench-aggregate: ./dest/bin/bench-aggregate.js
     bench-comment: ./dest/bin/bench-comment.js
     bench-markdown: ./dest/bin/bench-markdown.js
+    docs-preview-comment: ./dest/bin/docs-preview.js
   languageName: unknown
   linkType: soft