[chore] Revise README for content creation process

.github/scripts/post-precommit-suggestions.js

@@ -1,14 +1,14 @@
 /**
- * Posts pre-commit suggestions as GitHub PR comments
+ * Posts pre-commit suggestions as inline GitHub PR review comments
  * Each suggestion is tracked with a unique marker to avoid duplicates across multiple workflow runs
  */
 
 const crypto = require('crypto');  // used to hash suggestion content
 
 module.exports = async ({ github, context, diff }) => {
-  // Get all existing comments to check for duplicates
-  const { data: comments } = await github.rest.issues.listComments({
-    issue_number: context.issue.number,
+  // Get all existing review comments to check for duplicates
+  const { data: reviewComments } = await github.rest.pulls.listReviewComments({
+    pull_number: context.issue.number,
     owner: context.repo.owner,
     repo: context.repo.repo,
   });
@@ -75,6 +75,14 @@ module.exports = async ({ github, context, diff }) => {
     fileChanges.push({ file: currentFile, hunk: currentHunk });
   }
 
+  // Get the PR head commit SHA
+  const { data: pullRequest } = await github.rest.pulls.get({
+    pull_number: context.issue.number,
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+  });
+  const commitSha = pullRequest.head.sha;
+
   // Filter out changes that already have suggestions posted
   const newChanges = [];
   for (const change of fileChanges) {
@@ -85,47 +93,52 @@ module.exports = async ({ github, context, diff }) => {
     const hash = crypto.createHash('md5').update(file + suggestionContent).digest('hex').substring(0, 8);
     const marker = `<!-- pre-commit-suggestion-${hash} -->`;
 
-    // Check if this exact suggestion already exists
-    const alreadyExists = comments.some(comment => comment.body.includes(marker));
+    // Check if this exact suggestion already exists in review comments
+    const alreadyExists = reviewComments.some(comment => comment.body && comment.body.includes(marker));
 
     if (!alreadyExists) {
       newChanges.push({ ...change, marker });
     }
   }
 
-  // Only post a comment if there are new suggestions
+  // Only post inline review comments if there are new suggestions
   if (newChanges.length > 0) {
-    let body = "**Pre-commit formatting suggestions**\n\n";
-    body += "Pre-commit hooks found some formatting changes. You can apply each suggestion directly:\n\n";
+    // Create inline review comments for each suggestion
+    const comments = [];
 
     for (const change of newChanges) {
       const { file, hunk, marker } = change;
 
-      // Add the unique marker for this suggestion
-      body += marker + "\n";
-      body += `### \`${file}\` (line ${hunk.newStart})\n\n`;
-
-      // Create suggestion block
+      // Build the suggestion body with marker
+      let body = marker + "\n";
       body += "```suggestion\n";
       body += hunk.newLines.join('\n');
       if (hunk.newLines.length > 0 && !hunk.newLines[hunk.newLines.length - 1].endsWith('\n')) {
         body += '\n';
       }
-      body += "```\n\n";
+      body += "```";
+
+      // Calculate the correct line number
+      // newStart is where the hunk begins, then add context lines before changes, then the new lines
+      const lineNumber = hunk.newStart + hunk.contextBefore.length + hunk.newLines.length - 1;
+
+      comments.push({
+        path: file,
+        line: lineNumber,
+        side: "RIGHT",
+        body: body
+      });
     }
 
-    body += "---\n\n";
-    body += "🪄 **Quick fix:** Comment `fix formatting` below and I'll apply these changes automatically!\n\n";
-    body += "**Other options:**\n";
-    body += "- Apply the suggestions above directly in GitHub\n";
-    body += "- Run `pre-commit` locally and commit again\n\n";
-    body += "Need help? Check the [README](https://github.com/" + context.repo.owner + "/" + context.repo.repo + "/blob/main/README.md).\n";
-
-    await github.rest.issues.createComment({
-      issue_number: context.issue.number,
+    // Create a review with all inline comments
+    await github.rest.pulls.createReview({
+      pull_number: context.issue.number,
       owner: context.repo.owner,
       repo: context.repo.repo,
-      body: body
+      commit_id: commitSha,
+      event: "COMMENT",
+      body: "**Pre-commit formatting suggestions**\n\nPre-commit hooks found some formatting changes. You can apply each suggestion directly by clicking the \"Commit suggestion\" button, or run `pre-commit` locally and commit again.",
+      comments: comments
     });
   }
 };

README.md

@@ -50,27 +50,36 @@ Wave documentation is available as a Git submodule. Wave documentation is not ve
 
 To incorporate documentation changes from the Wave repository, run the following command: `git submodule update --recursive --remote`. This is mandatory, or published documentation cannot reflect any changes made to the Wave documentation since this command was last run. If you accidentally run the aforementioned command and want to revert, run the following command to revert to the previous commit ID for the Wave repository: `git submodule update --init`.
 
-## Writing new content
+## Write and edit content
 
-All new content originates in the docs repo. This is the source of truth.
+### Install pre-commit
 
-To publish new content:
+We use [pre-commit](https://pre-commit.com/) in our repo, which is invoked when a commit is made. When you (or Claude) are working locally and commit your changes in VS Code (or run `git commit`) the pre-commit hooks defined in the [precommit config file](./.pre-commit-config.yaml) are executed and may tweak the files you're staging.
+We currently use basic standard hooks to remove trailing whitespaces, make sure the file ends with a newline, we check yaml documents and we prevent very large files from getting committed. More hooks may get installed in the future.
 
-1. Run the following commands to set up [pre-commit](https://github.com/pre-commit/pre-commit) hooks:
+1. Open up a Terminal window and navigate to the `docs` directory.
+2. Run the following commands to set up [pre-commit](https://github.com/pre-commit/pre-commit) hooks:
 
    ```console
    $ pre-commit install
    $ pre-commit install-hooks
    ```
-
-1. Create a new branch in the docs repo, such as `gh-issue-number`.
-2. Complete the necessary work.
-3. Raise a PR to merge your updates to master
-4. Add relevant labels to your PR and request reviews from:
-   - Language review from a docs-codeowners member
-   - Technical review from the backend engineer or other SME closest to the feature
-5. Check and review the changes using the Netlify preview.
-6. Merge the PR once approved, if you created a new branch in the first step.
+You shouldn't experience any issues but if you do, share them in the #team-documentation channel so we can try help.
+
+:::note
+  You only have to install pre-commit once.
+:::
+
+### Make changes and create a PR
+
+1. In GitHub, or VS Code, create a new branch (e.g., `gh-issue-number`).
+3. Complete the necessary work, save your changes, and commit.
+4. In GitHub, create a PR to merge your updates to master.
+5. Add relevant labels to your PR and request reviews from:
+   - Language review from a `docs-codeowners` member.
+   - Technical review from the backend engineer or other SME closest to the feature.
+6. Check and review the changes using the Netlify preview.
+7. If you created the PR, the onus is on you to merge the PR once approved. This is the Edu team's policy, to ensure that PRs are never merged inadvertently. If you'd like one of us to merge it for you, please let us know. 
 
 Once merged to the master branch, the changes will be live immediately.