Don't spam pull requests with coverage comments.

.github/workflows/links.yml → .github/workflows/check-links.yml

@@ -1,11 +1,11 @@
-name: Links
+name: Check Links
 
 on:
   push:
   pull_request:
 
 jobs:
-  linkChecker:
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/coverage-gather.yml → .github/workflows/coverage-api.yml

@@ -45,15 +45,16 @@ jobs:
           total=`jq -r '.paths | keys | length' build/local-openapi.json`
           percent=$((current * 100 / total))
           echo "API specs implemented for $current/$total ($percent%) APIs."
-          cat >>"coverage.json" <<EOL
+          cat >>"coverage-api.json" <<EOL
           {
             "pull_request":${{ github.event.number }},
+            "sha":"${{ github.sha }}",
             "current":$current,
             "total":$total,
             "percent":$percent
           }
           EOL
       - uses: actions/upload-artifact@v4
         with:
-          name: coverage
-          path: coverage.json
+          name: coverage-api
+          path: coverage-api.json

.github/workflows/coverage-comment.yml

@@ -17,7 +17,8 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          name: coverage
+          pattern: coverage-*
+          merge-multiple: true
           run-id: ${{ github.event.workflow_run.id }}
 
       - name: 'Comment on PR'
@@ -26,11 +27,48 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const fs = require('fs');
-            const data = JSON.parse(fs.readFileSync('./coverage.json'));
-            console.log(data);
-            await github.issues.createComment({
+            const coverage_api = JSON.parse(fs.readFileSync('./coverage-api.json'));
+            console.log(coverage_api);
+
+            body = `API specs implemented for ${coverage_api.current}/${coverage_api.total} (${coverage_api.percent}%) APIs.`;
+            commit = `Commit ${coverage_api.sha}.`
+
+            const { data: comments } = await github.issues.listComments({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: data.pull_request,
-              body: `API specs implemented for ${data.current}/${data.total} (${data.percent}%) APIs.`
-            });
+              issue_number: coverage_api.pull_request
+            });
+
+            const existing_comment = comments.find(
+              comment => comment.body.startsWith("API specs implemented for ")
+            );
+
+            if (existing_comment && ! existing_comment.body.startsWith(body)) {
+              // change in coverage, delete existing comment
+              console.log(`Deleting ${existing_comment.url}.`);
+              await github.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: coverage_api.pull_request,
+                comment_id: existing_comment.id
+              });
+            }
+
+            if (existing_comment && existing_comment.body.startsWith(body)) {
+              // no change in coverage, update commit id
+              await github.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: coverage_api.pull_request,
+                comment_id: existing_comment.id,
+                body: body + "\n" + commit
+              });
+            } else {
+              // create a new comment
+              await github.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: coverage_api.pull_request,
+                body: body + "\n" + commit
+              });
+            }

.github/workflows/deploy.yml

@@ -1,5 +1,5 @@
 # deploys to https://opensearch-project.github.io/opensearch-api-specification/
-name: Deploy
+name: Deploy to GitHub Pages
 
 on:
   push:
@@ -14,7 +14,7 @@ permissions:
   contents: write
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout the repo

.github/workflows/tools.yml → .github/workflows/test-tools.yml

@@ -1,4 +1,4 @@
-name: Tools Testing
+name: Test Tools
 
 on:
   push:
@@ -11,7 +11,7 @@ on:
       - 'tools/**'
 
 jobs:
-  tools-tests:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

.github/workflows/lint.yml → .github/workflows/validate-spec.yml

@@ -13,7 +13,7 @@ on:
       - 'tools/src/linter/**'
 
 jobs:
-  lint-spec:
+  validate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

DEVELOPER_GUIDE.md

@@ -7,6 +7,8 @@
   - [Global Parameters](#global-parameters)
   - [OpenAPI Extensions](#openapi-extensions)
   - [Tools](#tools)
+    - [Merger](#merger)
+    - [Linter](#linter)
 
 # Developer Guide
 

coverage/README.md

@@ -2,4 +2,4 @@
 
 Builds the OpenAPI spec, and uses the [opensearch-api plugin](https://github.com/dblock/opensearch-api) and [openapi-diff](https://github.com/OpenAPITools/openapi-diff) to show the differences.
 
-API coverage is run on all pull requests via the [coverage workflow](../.github/workflows/coverage-gather.yml).
+API coverage is run on all pull requests via the [coverage workflow](../.github/workflows/coverage-api.yml).