From 5177a2883eb299d40fcfe4bf9871a036415e0cc4 Mon Sep 17 00:00:00 2001 From: Jess Hosman <1183847+jhosman@users.noreply.github.com> Date: Thu, 15 Dec 2022 12:00:00 -0700 Subject: [PATCH 1/2] Unify language in the API docs for pulls (#33171) --- content/rest/pulls/comments.md | 6 +++--- content/rest/pulls/index.md | 2 +- content/rest/pulls/pulls.md | 8 ++++---- content/rest/pulls/review-requests.md | 4 ++-- content/rest/pulls/reviews.md | 4 ++-- data/reusables/pull_requests/issues-media-types.md | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/content/rest/pulls/comments.md b/content/rest/pulls/comments.md index 05471a3293..30684816a8 100644 --- a/content/rest/pulls/comments.md +++ b/content/rest/pulls/comments.md @@ -1,7 +1,7 @@ --- title: Pull request review comments shortTitle: Review comments -intro: '' +intro: 'Use the REST API to interact with pull request review comments.' versions: fpt: '*' ghes: '*' @@ -13,8 +13,8 @@ miniTocMaxHeadingLevel: 3 allowTitleToDifferFromFilename: true --- -## About the Pull request review comments API +## About pull request review comments -Pull request review comments are comments on a portion of the unified diff made during a pull request review. Commit comments and issue comments are different from pull request review comments. You apply commit comments directly to a commit and you apply issue comments without referencing a portion of the unified diff. For more information, see "[Create a commit comment](/rest/reference/commits#create-a-commit-comment)" and "[Create an issue comment](/rest/reference/issues#create-an-issue-comment)." +Pull request review comments are comments made on a portion of the unified diff during a pull request review. These are different from commit comments and issue comments in a pull request. For more information, see "[Commit comments](/rest/commits/comments)" and "[Issue comments](/rest/issues/comments)." {% data reusables.pull_requests.issues-media-types %} diff --git a/content/rest/pulls/index.md b/content/rest/pulls/index.md index b354d18d2c..93c5b8aa7b 100644 --- a/content/rest/pulls/index.md +++ b/content/rest/pulls/index.md @@ -1,6 +1,6 @@ --- title: Pulls -intro: 'The Pulls API allows you to list, view, edit, create, and even merge pull requests.' +intro: 'Use the REST API to manage pull requests and pull request reviews.' redirect_from: - /v3/pulls - /rest/reference/pulls diff --git a/content/rest/pulls/pulls.md b/content/rest/pulls/pulls.md index c87bf98abe..af644f2949 100644 --- a/content/rest/pulls/pulls.md +++ b/content/rest/pulls/pulls.md @@ -1,6 +1,6 @@ --- title: Pulls -intro: 'The Pulls API allows you to list, view, edit, create, and even merge pull requests.' +intro: 'Use the REST API to interact with pull requests.' versions: fpt: '*' ghes: '*' @@ -11,11 +11,11 @@ topics: miniTocMaxHeadingLevel: 3 --- -## About the Pulls API +## About pull requests -The Pull Request API allows you to list, view, edit, create, and even merge pull requests. Comments on pull requests can be managed via the [Issue Comments API](/rest/reference/issues#comments). +You can list, view, edit, create, and merge pull requests using the REST API. For information about how to interact with comments on a pull request, see "[Issue comments](/rest/issues/comments)." -Every pull request is an issue, but not every issue is a pull request. For this reason, "shared" actions for both features, like manipulating assignees, labels and milestones, are provided within [the Issues API](/rest/reference/issues). +Pull requests are a type of issue. Any actions that are available in both pull requests and issues, like managing assignees, labels, and milestones, are provided by the REST API to manage issues. For more information, see "[Issues](/rest/issues)." ### Custom media types for pull requests diff --git a/content/rest/pulls/review-requests.md b/content/rest/pulls/review-requests.md index e01c7fb170..c11199af7f 100644 --- a/content/rest/pulls/review-requests.md +++ b/content/rest/pulls/review-requests.md @@ -1,6 +1,6 @@ --- title: Review requests -intro: '' +intro: 'Use the REST API to interact with review requests.' versions: fpt: '*' ghes: '*' @@ -11,6 +11,6 @@ topics: miniTocMaxHeadingLevel: 3 --- -## About the Review requests API +## About review requests Pull request authors and repository owners and collaborators can request a pull request review from anyone with write access to the repository. Each requested reviewer will receive a notification asking them to review the pull request. diff --git a/content/rest/pulls/reviews.md b/content/rest/pulls/reviews.md index 62bc53b156..c1734479f9 100644 --- a/content/rest/pulls/reviews.md +++ b/content/rest/pulls/reviews.md @@ -2,7 +2,7 @@ title: Pull request reviews shortTitle: Reviews allowTitleToDifferFromFilename: true -intro: '' +intro: 'Use the REST API to interact with pull request reviews.' versions: fpt: '*' ghes: '*' @@ -13,7 +13,7 @@ topics: miniTocMaxHeadingLevel: 3 --- -## About the Pull request reviews API +## About pull request reviews Pull Request Reviews are groups of pull request review comments on a pull request, grouped together with a state and optional body comment. diff --git a/data/reusables/pull_requests/issues-media-types.md b/data/reusables/pull_requests/issues-media-types.md index 87114284dc..d22ef0edaf 100644 --- a/data/reusables/pull_requests/issues-media-types.md +++ b/data/reusables/pull_requests/issues-media-types.md @@ -1,6 +1,6 @@ ### Custom media types -These are the supported media types for this API: +These are the supported media types for this set of endpoints: application/vnd.github.raw+json application/vnd.github.text+json From 898cfc616cc3f51b038d8818fd2a20d01c48f924 Mon Sep 17 00:00:00 2001 From: Jess Hosman <1183847+jhosman@users.noreply.github.com> Date: Thu, 15 Dec 2022 12:00:23 -0700 Subject: [PATCH 2/2] Unify language in the API docs for "Overview" (#33376) Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com> --- content/rest/overview/api-previews.md | 4 ++-- content/rest/overview/media-types.md | 5 ++--- content/rest/overview/resources-in-the-rest-api.md | 14 +++++++------- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/content/rest/overview/api-previews.md b/content/rest/overview/api-previews.md index 9ec7f2ffc9..721c6ac004 100644 --- a/content/rest/overview/api-previews.md +++ b/content/rest/overview/api-previews.md @@ -10,7 +10,7 @@ topics: --- -API previews let you try out new APIs and changes to existing API methods before they become part of the official GitHub API. +API previews let you try out new endpoints and changes to existing endpoints before they become part of the official {% data variables.product.prodname_dotcom %} API. During the preview period, we may change some features based on developer feedback. If we do make changes, we'll announce them on the [developer blog](https://developer.github.com/changes/) without advance notice. @@ -19,7 +19,7 @@ To access an API preview, you'll need to provide a custom [media type](/rest/ove {% ifversion ghes < 3.4 %} ## Content attachments -You can now provide more information in GitHub for URLs that link to registered domains by using the {% data variables.product.prodname_unfurls %} API. See "[Using content attachments](/apps/using-content-attachments/)" for more details. +You can now provide more information in {% data variables.product.prodname_dotcom %} for URLs that link to registered domains by using the API to manage {% data variables.product.prodname_unfurls %}. For more information, see "[Using content attachments](/apps/using-content-attachments/)." **Custom media types:** `corsair-preview` **Announced:** [2018-12-10](https://developer.github.com/changes/2018-12-10-content-attachments-api/) diff --git a/content/rest/overview/media-types.md b/content/rest/overview/media-types.md index 34c18a10d6..8bdb3aff9c 100644 --- a/content/rest/overview/media-types.md +++ b/content/rest/overview/media-types.md @@ -41,7 +41,7 @@ put it after `github`: ## Comment body properties -The body of a comment can be written in [GitHub Flavored Markdown][gfm], [issues](/rest/reference/issues), [issue comments](/rest/reference/issues#comments), [pull request comments](/rest/reference/pulls#comments), and the [gist comments](/rest/reference/gists#comments) APIs all accept these same media types: +The body of a comment can be written in [{% data variables.product.prodname_dotcom %} Flavored Markdown][gfm]. The APIs to manage [issues](/rest/reference/issues), [issue comments](/rest/reference/issues#comments), [pull request comments](/rest/reference/pulls#comments), and [gist comments](/rest/reference/gists#comments) all accept these same media types: ### Raw @@ -91,8 +91,7 @@ Return the raw blob data. ## Commits, commit comparison, and pull requests -The [commits API](/rest/reference/repos#commits) and [pull requests API](/rest/reference/pulls) support -[diff][git-diff] and [patch][git-patch] formats: +The REST API to manage [commits](/rest/reference/repos#commits) and [pull requests](/rest/reference/pulls) support [diff][git-diff] and [patch][git-patch] formats: ### diff diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index 72517b3318..84cc8b6bb8 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -321,7 +321,7 @@ If {% data variables.product.prodname_dotcom %} takes more than 10 seconds to pr Different types of API requests to {% data variables.location.product_location %} are subject to different rate limits. -Additionally, the Search API has dedicated limits. For more information, see "[Search](/rest/reference/search#rate-limit)" in the REST API documentation. +Additionally, the Search endpoints have dedicated limits. For more information, see "[Search](/rest/reference/search#rate-limit)" in the REST API documentation. {% data reusables.enterprise.rate_limit %} @@ -359,15 +359,15 @@ When using `GITHUB_TOKEN`, the rate limit is 1,000 requests per hour per reposit ### Checking your rate limit status -The Rate Limit API and a response's HTTP headers are authoritative sources for the current number of API calls available to you or your app at any given time. +You can use the REST API to find the current number of API calls available to you or your app at any given time. -#### Rate Limit API +#### API to manage rate limits -You can use the Rate Limit API to check your rate limit status without incurring a hit to the current limit. For more information, see "[Rate limit](/rest/reference/rate-limit)." +You can use the REST API to check your rate limit status without incurring a hit to the current limit. For more information, see "[Rate limit](/rest/reference/rate-limit)." #### Rate limit HTTP headers -The returned HTTP headers of any API request show your current rate limit status: +You can view the returned headers of any API request to see your current rate limit status: ```shell $ curl -I {% data variables.product.api_url_pre %}/users/octocat @@ -655,7 +655,7 @@ Note that these rules apply only to data passed to the API, not to data returned ### Explicitly providing an ISO 8601 timestamp with timezone information -For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the [Commits API](/rest/reference/git#commits). +For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the API to manage commits. For more information, see "[Commits](/rest/reference/git#commits)." These timestamps look something like `2014-02-27T15:05:06+01:00`. Also see [this example](/rest/reference/git#example-input) for how these timestamps can be specified. @@ -667,7 +667,7 @@ It is possible to supply a `Time-Zone` header which defines a timezone according $ curl -H "Time-Zone: Europe/Amsterdam" -X POST {% data variables.product.api_url_pre %}/repos/github/linguist/contents/new_file.md ``` -This means that we generate a timestamp for the moment your API call is made in the timezone this header defines. For example, the [Contents API](/rest/reference/repos#contents) generates a git commit for each addition or change and uses the current time as the timestamp. This header will determine the timezone used for generating that current timestamp. +This means that we generate a timestamp for the moment your API call is made in the timezone this header defines. For example, the API to manage contents generates a git commit for each addition or change and uses the current time as the timestamp. For more information, see "[Contents](/rest/reference/repos#contents)." This header will determine the timezone used for generating that current timestamp. ### Using the last known timezone for the user