From eb8e9414a39fbe5fe46f98bb23b72bcef1c89a8c Mon Sep 17 00:00:00 2001 From: Jess Hosman <1183847+jhosman@users.noreply.github.com> Date: Wed, 14 Dec 2022 15:25:35 -0700 Subject: [PATCH] Unify language in the API docs for commits (#33369) --- content/rest/commits/comments.md | 6 +++--- content/rest/commits/commits.md | 3 +-- content/rest/commits/index.md | 2 +- content/rest/commits/statuses.md | 10 +++++----- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/content/rest/commits/comments.md b/content/rest/commits/comments.md index 33363e03da..4a530ca702 100644 --- a/content/rest/commits/comments.md +++ b/content/rest/commits/comments.md @@ -1,6 +1,6 @@ --- title: Commit comments -intro: The Commit comments API lets you create and edit comments that relate to specific commits. +intro: Use the REST API to interact with commit comments. versions: fpt: '*' ghes: '*' @@ -12,9 +12,9 @@ miniTocMaxHeadingLevel: 3 allowTitleToDifferFromFilename: true --- -## About the commit comments API +## About commit comments -The Commit comments API lets you create and edit comments that relate to specific commits. +You can create, edit, and view commit comments using the REST API. A commit comment is a comment made on a specfic commit. For more information, see "[Working with comments](/rest/guides/working-with-comments#commit-comments)." ### Custom media types for commit comments diff --git a/content/rest/commits/commits.md b/content/rest/commits/commits.md index 44c939f604..c87eaac058 100644 --- a/content/rest/commits/commits.md +++ b/content/rest/commits/commits.md @@ -1,6 +1,6 @@ --- title: Commits -intro: 'The Commits API allows you to list, view, and compare commits in a repository. You can also interact with commit comments and commit statuses.' +intro: 'Use the REST API to interact with commits.' versions: fpt: '*' ghes: '*' @@ -10,4 +10,3 @@ topics: - API miniTocMaxHeadingLevel: 3 --- - diff --git a/content/rest/commits/index.md b/content/rest/commits/index.md index e0563cf2f3..5c2b0eced8 100644 --- a/content/rest/commits/index.md +++ b/content/rest/commits/index.md @@ -1,6 +1,6 @@ --- title: Commits -intro: 'The commits API allows you to list, view, and compare commits in a repository. You can also interact with commit comments and commit statuses.' +intro: 'Use the REST API to interact with commits.' allowTitleToDifferFromFilename: true versions: fpt: '*' diff --git a/content/rest/commits/statuses.md b/content/rest/commits/statuses.md index b0e078661d..735babdeab 100644 --- a/content/rest/commits/statuses.md +++ b/content/rest/commits/statuses.md @@ -1,6 +1,6 @@ --- title: Commit statuses -intro: 'The Commit status API allows external services to mark commits with a status, which is then reflected in pull requests involving those commits.' +intro: 'Use the REST API to interact with commit statuses.' versions: fpt: '*' ghes: '*' @@ -12,14 +12,14 @@ miniTocMaxHeadingLevel: 3 allowTitleToDifferFromFilename: true --- -## About the Commit statuses API +## About commit statuses -The Commit status API allows external services to mark commits with an `error`, `failure`, `pending`, or `success` state, which is then reflected in pull requests involving those commits. Statuses can also include an optional `description` and `target_url`, and we highly recommend providing them as they make statuses much more useful in the GitHub UI. +You can use the REST API to allow external services to mark commits with an `error`, `failure`, `pending`, or `success` state, which is then reflected in pull requests involving those commits. Statuses can also include an optional `description` and `target_url`, and we highly recommend providing them as they make statuses much more useful in the GitHub UI. As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. The `target_url` would be the full URL to the build output, and the `description` would be the high level summary of what happened with the build. -Statuses can include a `context` to indicate what service is providing that status. For example, you may have your continuous integration service push statuses with a context of `ci`, and a security audit tool push statuses with a context of `security`. You can then use the [Get the combined status for a specific reference](/rest/reference/commits#get-the-combined-status-for-a-specific-reference) to retrieve the whole status for a commit. +Statuses can include a `context` to indicate what service is providing that status. For example, you may have your continuous integration service push statuses with a context of `ci`, and a security audit tool push statuses with a context of `security`. You can then use the REST API to [Get the combined status for a specific reference](/rest/commits/statuses#get-the-combined-status-for-a-specific-reference) to retrieve the whole status for a commit. Note that the `repo:status` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to statuses **without** also granting access to repository code, while the `repo` scope grants permission to code as well as statuses. -If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the [Checks API](/rest/reference/checks). +If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the REST API to manage checks. For more information, see "[Checks](/rest/reference/checks)."