Update description of GitHub commit status badge (#10198)

* [GitHub] update description of commit status badge * fix typo * Add pull request check * regex to english
badges · May 26, 2024 · 427b24c · 427b24c
1 parent e43cb0c
commit 427b24c
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 23 deletions.
diff --git a/services/github/github-checks-status.service.js b/services/github/github-checks-status.service.js
@@ -1,8 +1,21 @@
 import Joi from 'joi'
-import { pathParams } from '../index.js'
+import { pathParam } from '../index.js'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
-import { documentation, httpErrorsFor } from './github-helpers.js'
+import {
+  documentation as commonDocumentation,
+  httpErrorsFor,
+} from './github-helpers.js'
+
+const description = `
+Displays the status of a tag, commit, or branch, as reported by the Commit Status API.
+Nowadays, GitHub Actions and many third party integrations report state via the
+Checks API. If this badge does not show expected values, please try out our
+corresponding Check Runs badge instead. You can read more about status checks in
+the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).
+
+${commonDocumentation}
+`
 
 const schema = Joi.object({
   state: isBuildStatus,
@@ -16,24 +29,40 @@ export default class GithubChecksStatus extends GithubAuthV3Service {
   }
 
   static openApi = {
-    '/github/checks-status/{user}/{repo}/{ref}': {
+    '/github/checks-status/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'GitHub branch status',
+        description,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          pathParam({ name: 'branch', example: 'master' }),
+        ],
+      },
+    },
+    '/github/checks-status/{user}/{repo}/{commit}': {
+      get: {
+        summary: 'GitHub commit status',
+        description,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          pathParam({
+            name: 'commit',
+            example: '91b108d4b7359b2f8794a4614c11cb1157dc9fff',
+          }),
+        ],
+      },
+    },
+    '/github/checks-status/{user}/{repo}/{tag}': {
       get: {
-        summary: 'GitHub tag checks state',
-        description: documentation,
-        parameters: pathParams(
-          {
-            name: 'user',
-            example: 'badges',
-          },
-          {
-            name: 'repo',
-            example: 'shields',
-          },
-          {
-            name: 'ref',
-            example: '3.3.0',
-          },
-        ),
+        summary: 'GitHub tag status',
+        description,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          pathParam({ name: 'tag', example: '3.3.0' }),
+        ],
       },
     },
   }

diff --git a/services/github/github-pull-request-check-state.service.js b/services/github/github-pull-request-check-state.service.js
@@ -3,7 +3,20 @@ import countBy from 'lodash.countby'
 import { pathParams } from '../index.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
 import { fetchIssue } from './github-common-fetch.js'
-import { documentation, httpErrorsFor } from './github-helpers.js'
+import {
+  documentation as commonDocumentation,
+  httpErrorsFor,
+} from './github-helpers.js'
+
+const description = `
+Displays the status of a pull request, as reported by the Commit Status API.
+Nowadays, GitHub Actions and many third party integrations report state via the
+Checks API. If this badge does not show expected values, please try out our
+corresponding Check Runs badge instead. You can read more about status checks in
+the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).
+
+${commonDocumentation}
+`
 
 const schema = Joi.object({
   state: Joi.equal('failure', 'pending', 'success').required(),
@@ -26,8 +39,8 @@ export default class GithubPullRequestCheckState extends GithubAuthV3Service {
   static openApi = {
     '/github/status/s/pulls/{user}/{repo}/{number}': {
       get: {
-        summary: 'GitHub pull request check state',
-        description: documentation,
+        summary: 'GitHub pull request status',
+        description,
         parameters: pathParams(
           {
             name: 'user',
@@ -47,7 +60,7 @@ export default class GithubPullRequestCheckState extends GithubAuthV3Service {
     '/github/status/contexts/pulls/{user}/{repo}/{number}': {
       get: {
         summary: 'GitHub pull request check contexts',
-        description: documentation,
+        description,
         parameters: pathParams(
           {
             name: 'user',