From 3343658ce8e589b69b687a5fd25e22010f66e78f Mon Sep 17 00:00:00 2001
From: dblock <dblock@amazon.com>
Date: Thu, 16 May 2024 13:23:33 -0400
Subject: [PATCH 1/3] Renamed workflows for consitency.

Signed-off-by: dblock <dblock@amazon.com>
---
 .../{coverage-gather.yml => coverage-api.yml}         |  6 +++---
 .github/workflows/coverage-comment.yml                | 11 ++++++-----
 .github/workflows/{tools.yml => tests-tools.yml}      |  4 ++--
 DEVELOPER_GUIDE.md                                    |  2 ++
 coverage/README.md                                    |  2 +-
 5 files changed, 14 insertions(+), 11 deletions(-)
 rename .github/workflows/{coverage-gather.yml => coverage-api.yml} (95%)
 rename .github/workflows/{tools.yml => tests-tools.yml} (91%)

diff --git a/.github/workflows/coverage-gather.yml b/.github/workflows/coverage-api.yml
similarity index 95%
rename from .github/workflows/coverage-gather.yml
rename to .github/workflows/coverage-api.yml
index 887132ebd..e40c9a373 100644
--- a/.github/workflows/coverage-gather.yml
+++ b/.github/workflows/coverage-api.yml
@@ -45,7 +45,7 @@ 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 }},
             "current":$current,
@@ -55,5 +55,5 @@ jobs:
           EOL
       - uses: actions/upload-artifact@v4
         with:
-          name: coverage
-          path: coverage.json
\ No newline at end of file
+          name: coverage-api
+          path: coverage-api.json
\ No newline at end of file
diff --git a/.github/workflows/coverage-comment.yml b/.github/workflows/coverage-comment.yml
index 959d7a328..d3f297ba0 100644
--- a/.github/workflows/coverage-comment.yml
+++ b/.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,11 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const fs = require('fs');
-            const data = JSON.parse(fs.readFileSync('./coverage.json'));
-            console.log(data);
+            const coverage_api = JSON.parse(fs.readFileSync('./coverage-api.json'));
+            console.log(coverage_api);
             await github.issues.createComment({
               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,
+              body: `API specs implemented for ${coverage_api.current}/${coverage_api.total} (${coverage_api.percent}%) APIs.`
             });
\ No newline at end of file
diff --git a/.github/workflows/tools.yml b/.github/workflows/tests-tools.yml
similarity index 91%
rename from .github/workflows/tools.yml
rename to .github/workflows/tests-tools.yml
index 0cae7671e..536ba13a2 100644
--- a/.github/workflows/tools.yml
+++ b/.github/workflows/tests-tools.yml
@@ -1,4 +1,4 @@
-name: Tools Testing
+name: Test Tools
 
 on:
   push:
@@ -11,7 +11,7 @@ on:
       - 'tools/**'
 
 jobs:
-  tools-tests:
+  tests-tools:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
index ca19a0bd3..497cc8c25 100644
--- a/DEVELOPER_GUIDE.md
+++ b/DEVELOPER_GUIDE.md
@@ -7,6 +7,8 @@
   - [Global Parameters](#global-parameters)
   - [OpenAPI Extensions](#openapi-extensions)
   - [Tools](#tools)
+    - [Merger](#merger)
+    - [Linter](#linter)
 
 # Developer Guide
 
diff --git a/coverage/README.md b/coverage/README.md
index 89ae4e76b..3afdb91b0 100644
--- a/coverage/README.md
+++ b/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).

From b8faa583c10ea30cc054d9f8c25458c20de989b8 Mon Sep 17 00:00:00 2001
From: dblock <dblock@amazon.com>
Date: Thu, 16 May 2024 13:34:21 -0400
Subject: [PATCH 2/3] Only add a comment if coverage has changed.

Signed-off-by: dblock <dblock@amazon.com>
---
 .github/workflows/coverage-api.yml     |  1 +
 .github/workflows/coverage-comment.yml | 45 +++++++++++++++++++++++---
 2 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/coverage-api.yml b/.github/workflows/coverage-api.yml
index e40c9a373..482e242bc 100644
--- a/.github/workflows/coverage-api.yml
+++ b/.github/workflows/coverage-api.yml
@@ -48,6 +48,7 @@ jobs:
           cat >>"coverage-api.json" <<EOL
           {
             "pull_request":${{ github.event.number }},
+            "sha":"${{ github.sha }}",
             "current":$current,
             "total":$total,
             "percent":$percent
diff --git a/.github/workflows/coverage-comment.yml b/.github/workflows/coverage-comment.yml
index d3f297ba0..48de6228c 100644
--- a/.github/workflows/coverage-comment.yml
+++ b/.github/workflows/coverage-comment.yml
@@ -29,9 +29,46 @@ jobs:
             const fs = require('fs');
             const coverage_api = JSON.parse(fs.readFileSync('./coverage-api.json'));
             console.log(coverage_api);
-            await github.issues.createComment({
+
+            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: coverage_api.pull_request,
-              body: `API specs implemented for ${coverage_api.current}/${coverage_api.total} (${coverage_api.percent}%) APIs.`
-            });
\ No newline at end of file
+              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
+              });
+            }
\ No newline at end of file

From 5f22dff0c76abc8938f6db9208f47bd3b1386d27 Mon Sep 17 00:00:00 2001
From: dblock <dblock@amazon.com>
Date: Thu, 16 May 2024 14:51:35 -0400
Subject: [PATCH 3/3] More renames for consistency.

Signed-off-by: dblock <dblock@amazon.com>
---
 .github/workflows/{links.yml => check-links.yml}      | 4 ++--
 .github/workflows/deploy.yml                          | 4 ++--
 .github/workflows/{tests-tools.yml => test-tools.yml} | 2 +-
 .github/workflows/{lint.yml => validate-spec.yml}     | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)
 rename .github/workflows/{links.yml => check-links.yml} (93%)
 rename .github/workflows/{tests-tools.yml => test-tools.yml} (96%)
 rename .github/workflows/{lint.yml => validate-spec.yml} (97%)

diff --git a/.github/workflows/links.yml b/.github/workflows/check-links.yml
similarity index 93%
rename from .github/workflows/links.yml
rename to .github/workflows/check-links.yml
index bfdd4df3d..d4b521959 100644
--- a/.github/workflows/links.yml
+++ b/.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
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index c0ec9b73c..c180a53bd 100644
--- a/.github/workflows/deploy.yml
+++ b/.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
diff --git a/.github/workflows/tests-tools.yml b/.github/workflows/test-tools.yml
similarity index 96%
rename from .github/workflows/tests-tools.yml
rename to .github/workflows/test-tools.yml
index 536ba13a2..81121b6bb 100644
--- a/.github/workflows/tests-tools.yml
+++ b/.github/workflows/test-tools.yml
@@ -11,7 +11,7 @@ on:
       - 'tools/**'
 
 jobs:
-  tests-tools:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
diff --git a/.github/workflows/lint.yml b/.github/workflows/validate-spec.yml
similarity index 97%
rename from .github/workflows/lint.yml
rename to .github/workflows/validate-spec.yml
index 2d7bd2f26..5f26fec45 100644
--- a/.github/workflows/lint.yml
+++ b/.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