fix: update in-code documentation for `repos.createOrUpdateFileConten…

…ts` (`PUT /repos/{owner}/{repo}/contents/{path}`) and `repos.deleteFile` (`DELETE /repos/{owner}/{repo}/contents/{path}`) to clarify that calling them in parallel may lead to conflicts (#556)

WIP octokit/openapi updated

docs/issues/list.md

@@ -39,7 +39,7 @@ Indicates which sorts of issues to return. `assigned` means issues assigned to y
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the issues to return.
 
 </td></tr>
 <tr><td>labels</td><td>no</td><td>
@@ -49,7 +49,7 @@ A list of comma separated label names. Example: `bug,ui,@high`
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-What to sort results by. Can be either `created`, `updated`, `comments`.
+What to sort results by.
 
 </td></tr>
 <tr><td>direction</td><td>no</td><td>

docs/issues/listForAuthenticatedUser.md

@@ -37,7 +37,7 @@ Indicates which sorts of issues to return. `assigned` means issues assigned to y
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the issues to return.
 
 </td></tr>
 <tr><td>labels</td><td>no</td><td>
@@ -47,7 +47,7 @@ A list of comma separated label names. Example: `bug,ui,@high`
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-What to sort results by. Can be either `created`, `updated`, `comments`.
+What to sort results by.
 
 </td></tr>
 <tr><td>direction</td><td>no</td><td>

docs/issues/listForOrg.md

@@ -44,7 +44,7 @@ Indicates which sorts of issues to return. `assigned` means issues assigned to y
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the issues to return.
 
 </td></tr>
 <tr><td>labels</td><td>no</td><td>
@@ -54,7 +54,7 @@ A list of comma separated label names. Example: `bug,ui,@high`
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-What to sort results by. Can be either `created`, `updated`, `comments`.
+What to sort results by.
 
 </td></tr>
 <tr><td>direction</td><td>no</td><td>

docs/issues/listForRepo.md

@@ -50,7 +50,7 @@ If an `integer` is passed, it should refer to a milestone by its `number` field.
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the issues to return.
 
 </td></tr>
 <tr><td>assignee</td><td>no</td><td>
@@ -75,7 +75,7 @@ A list of comma separated label names. Example: `bug,ui,@high`
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-What to sort results by. Can be either `created`, `updated`, `comments`.
+What to sort results by.
 
 </td></tr>
 <tr><td>direction</td><td>no</td><td>

docs/markdown/render.md

@@ -32,7 +32,7 @@ The Markdown text to render in HTML.
 </td></tr>
 <tr><td>mode</td><td>no</td><td>
 
-The rendering mode. Can be either `markdown` or `gfm`.
+The rendering mode.
 
 </td></tr>
 <tr><td>context</td><td>no</td><td>

docs/orgs/listMembershipsForAuthenticatedUser.md

@@ -25,7 +25,7 @@ octokit.rest.orgs.listMembershipsForAuthenticatedUser();
   <tbody>
     <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the memberships to return. Can be either `active` or `pending`. If not specified, the API returns both active and pending memberships.
+Indicates the state of the memberships to return. If not specified, the API returns both active and pending memberships.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/projects/listForOrg.md

@@ -34,7 +34,7 @@ The organization name. The name is not case sensitive.
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the projects to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the projects to return.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/projects/listForRepo.md

@@ -40,7 +40,7 @@ The name of the repository. The name is not case sensitive.
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the projects to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the projects to return.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/projects/listForUser.md

@@ -32,7 +32,7 @@ The handle for the GitHub user account.
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Indicates the state of the projects to return. Can be either `open`, `closed`, or `all`.
+Indicates the state of the projects to return.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/pulls/list.md

@@ -55,12 +55,12 @@ Filter pulls by base branch name. Example: `gh-pages`.
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-What to sort results by. Can be either `created`, `updated`, `popularity` (comment count) or `long-running` (age, filtering by pulls updated in the last month).
+What to sort results by. `popularity` will sort by the number of comments. `long-running` will sort by date created and will limit the results to pull requests that have been open for more than a month and have had activity within the past month.
 
 </td></tr>
 <tr><td>direction</td><td>no</td><td>
 
-The direction of the sort. Can be either `asc` or `desc`. Default: `desc` when sort is `created` or sort is not specified, otherwise `asc`.
+The direction of the sort. Default: `desc` when sort is `created` or sort is not specified, otherwise `asc`.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/pulls/listReviewComments.md

@@ -51,7 +51,7 @@ The property to sort the results by. `created` means when the repository was sta
 </td></tr>
 <tr><td>direction</td><td>no</td><td>
 
-Can be either `asc` or `desc`. Ignored without `sort` parameter.
+The direction to sort results. Ignored without `sort` parameter.
 
 </td></tr>
 <tr><td>since</td><td>no</td><td>

docs/pulls/listReviewCommentsForRepo.md

@@ -43,7 +43,7 @@ The name of the repository. The name is not case sensitive.
 </td></tr>
 <tr><td>direction</td><td>no</td><td>
 
-Can be either `asc` or `desc`. Ignored without `sort` parameter.
+The direction to sort results. Ignored without `sort` parameter.
 
 </td></tr>
 <tr><td>since</td><td>no</td><td>

docs/repos/createOrUpdateFileContents.md

@@ -10,6 +10,8 @@ type: API method
 
 Creates a new file or replaces an existing file in a repository. You must authenticate using an access token with the `workflow` scope to use this endpoint.
 
+**Note:** If you use this endpoint and the "[Delete a file](https://docs.github.com/rest/reference/repos/#delete-file)" endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead.
+
 ```js
 octokit.rest.repos.createOrUpdateFileContents({
         owner,

docs/repos/deleteFile.md

@@ -16,6 +16,8 @@ The `author` section is optional and is filled in with the `committer` informati
 
 You must provide values for both `name` and `email`, whether you choose to use `author` or `committer`. Otherwise, you'll receive a `422` status code.
 
+**Note:** If you use this endpoint and the "[Create or update file contents](https://docs.github.com/rest/reference/repos/#create-or-update-file-contents)" endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead.
+
 ```js
 octokit.rest.repos.deleteFile({
   owner,

docs/repos/listForks.md

@@ -38,7 +38,7 @@ The name of the repository. The name is not case sensitive.
 </td></tr>
 <tr><td>sort</td><td>no</td><td>
 
-The sort order. Can be either `newest`, `oldest`, or `stargazers`.
+The sort order. `stargazers` will sort by star count.
 
 </td></tr>
 <tr><td>per_page</td><td>no</td><td>

docs/secretScanning/updateAlert.md

@@ -51,7 +51,7 @@ The number that identifies an alert. You can find this at the end of the URL for
 </td></tr>
 <tr><td>state</td><td>yes</td><td>
 
-Sets the state of the secret scanning alert. Can be either `open` or `resolved`. You must provide `resolution` when you set the state to `resolved`.
+Sets the state of the secret scanning alert. You must provide `resolution` when you set the state to `resolved`.
 
 </td></tr>
 <tr><td>resolution</td><td>no</td><td>