Merge remote-tracking branch 'internal/master' into gdp-round-2

tclem · tclem · commit eebf5d243d27 · 2014-03-05T16:23:48.000-08:00
diff --git a/content/changes/2014-01-29-audit-org-members-for-2fa.md b/content/changes/2014-01-29-audit-org-members-for-2fa.md
@@ -11,7 +11,7 @@ We've added a [new filter][filter] for listing members of an organization withou
 
 <pre class="terminal">
 $ curl -H "Authorization: token [yours]" \
-       https://api.github.com/orgs/octokit/members\?filter\=2fa_disabled
+       https://api.github.com/orgs/[orgname]/members\?filter\=2fa_disabled
 </pre>
 
 The new filter is available for owners of organizations with private
diff --git a/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md b/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md
@@ -0,0 +1,35 @@
+---
+kind: change
+title: Finer-grained OAuth scopes for SSH keys
+created_at: 2014-02-24
+author_name: pengwynn
+---
+As [we announced][blog], we've made some important changes to the way that API consumers manage SSH keys.
+
+## Finer-grained OAuth scopes
+
+To help third party applications request only permissions that they need, the API now supports three new [scopes][] for working with a user's public SSH keys.
+
+- `read:public_key` provides read access to the user's SSH keys
+- `write:public_key` allows an app to read existing keys and create new ones
+- `admin:public_key` enables an app to read, write, and delete keys
+
+## Changes to `user` scope
+
+Historically, `user` scope has provided full access to manage a user's SSH keys. Now that we have dedicated scopes for managing a user's SSH keys, we have removed those permissions from the `user` scope. Now `user` scope will no longer provide access to SSH keys. Applications that need this access should request one of the new scopes described above.
+
+## Keys are now immutable
+
+To simplify the security audit trail for SSH keys, we're making keys immutable. API consumers can continue to create keys and delete keys as needed, but keys can no longer be changed. To change an existing key, API consumers should delete the existing key and create a new one with the desired attributes. This change applies both to a [user's SSH keys][user-keys] and a [repository's deploy keys][deploy-keys].
+
+## Deleting keys when revoking a token
+
+Also any keys created via an OAuth token from this point forward will be deleted when that token is revoked.
+
+As always, if you have any questions or feedback, [please get in touch][contact].
+
+[contact]: https://github.com/contact?form[subject]=API+improvements+for+SSH+keys
+[scopes]: /v3/oauth/#scopes
+[user-keys]: /v3/users/keys/
+[deploy-keys]: /v3/repos/keys/
+[blog]: https://github.com/blog/1786-enhanced-oauth-security-for-ssh-keys
diff --git a/content/changes/2014-02-25-organization-oauth-scopes.md b/content/changes/2014-02-25-organization-oauth-scopes.md
@@ -0,0 +1,21 @@
+---
+kind: change
+title: OAuth scopes for organization and team resources
+created_at: 2014-02-25
+author_name: pengwynn
+---
+As a follow up to [the new scopes][yesterday] we announced yesterday, we've
+introduced even more OAuth scopes for working with organization and team
+resources:
+
+- `read:org` provides read-only access to organizations, teams, and membership.
+- `write:org` allows an application to publicize and unpublicize an organization membership.
+- `admin:org` enables an application to fully manage organizations, teams, and memberships.
+
+Check out [the full list of OAuth scopes][scopes] supported by the API to
+ensure your application asks for only the permissions it needs. As always, if
+you have any questions or feedback, [get in touch][contact].
+
+[yesterday]: http://developer.github.com/changes/2014-02-24-finer-grained-scopes-for-ssh-keys/
+[scopes]: /v3/oauth/#scopes
+[contact]: https://github.com/contact?form[subject]=API+org+scopes
diff --git a/content/changes/2014-02-28-issue-and-pull-query-enhancements.md b/content/changes/2014-02-28-issue-and-pull-query-enhancements.md
@@ -0,0 +1,27 @@
+---
+kind: change
+title: Query enhancements for listing issues and pull requests
+created_at: 2014-02-28
+author_name: pengwynn
+---
+We've made it even easier to list all [issues][] and [pull requests][] via the API.
+The `state` parameter now supports a value of `all` that will return issues and
+pull requests regardless of state.
+
+<pre class="terminal">
+$ curl https://api.github.com/repos/atom/vim-mode/issues\?state\=all
+</pre>
+
+We've also introduced new sorting options for [listing pull requests][pull
+requests]. You can now sort pull requests by `created`, `updated`,
+`popularity`, and `long-running`.
+
+<pre class="terminal">
+$ curl https://api.github.com/repos/rails/rails/pulls\?sort\=long-running\&direction\=desc
+</pre>
+
+Happy querying. If you have any questions or feedback [get in touch][contact].
+
+[issues]: /v3/issues/#list-issues
+[pull requests]: /v3/pulls/#list-pull-requests
+[contact]: https://github.com/contact?form[subject]=API+query+enhancements
diff --git a/content/changes/2014-03-03-deployments-api-updates.md b/content/changes/2014-03-03-deployments-api-updates.md
@@ -0,0 +1,21 @@
+---
+kind: change
+title: New Payload Format for Deployments
+created_at: 2014-03-03
+author_name: atmos
+---
+
+As we [iterate on the preview][january-deployment-api-post] for the new Deployment API, we're making sure that it's friendly to work with for the apps built on top of it.
+
+## Deserialize Deployment Payloads
+
+To make the API even easier to use, we'll now return your custom payload as a JSON object along with the rest of the Deployment resource. No need to parse it as JSON again.
+
+## Code You Need to Update
+
+You should only need to remove the JSON parsing if you're taking advantage of the custom payloads. The formats for creating Deployments remain unchanged.
+
+As always, if you have any questions or feedback, please [get in touch][contact].
+
+[january-deployment-api-post]: /changes/2014-01-09-preview-the-new-deployments-api/
+[contact]: https://github.com/contact?form[subject]=Deployments+API
diff --git a/content/changes/2014-03-04-timezone-handling-changes.html b/content/changes/2014-03-04-timezone-handling-changes.html
@@ -0,0 +1,54 @@
+---
+kind: change
+title: Improved timezone handling in the API
+created_at: 2014-03-04
+author_name: dbussink
+---
+
+We have improved support for handling timezones in our API. For example, if you
+create commits through the API, we now allow for specifying timezone information
+more accurately.
+
+We apply the following rules, in order of priority, to determine timezone
+information for API calls:
+
+#### Explicitly provide 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](/v3/git/commits) which allows
+for specifying the `date` property.
+
+<%= json "message"=> "my commit message", \
+    "author"=> \
+    {"name" => "Dirkjan Bussink", "email" => "d.bussink@gmail.com", \
+    "date" => "2014-02-27T15:05:06+01:00"}, \
+    "parents"=>["7d1b31e74ee336d15cbd21741bc88a537ed063a0"], \
+    "tree"=>"827efc6d56897b048c772eb4087f854f46256132" %>
+
+#### Using the `Time-Zone` header
+
+It is possible to supply a `Time-Zone` header which defines a timezone according
+to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+    $ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/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](/v3/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.
+
+#### Using the last known timezone for the user
+
+If no `Time-Zone` header is specified and you make an authenticated call to the
+API, we use the last known timezone for the authenticated user. The last know
+timezone is updated whenever you browse the GitHub.com website.
+
+#### UTC
+
+If the steps above don't result in any information, we use UTC as the timezone
+to create the git commit.
+
+If you have any questions or feedback, don't hesitate to [contact] us!
+
+[contact]: https://github.com/contact?form[subject]=API+timezones
diff --git a/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md b/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md
@@ -0,0 +1,21 @@
+---
+kind: change
+title: "Reminder: March 12 Cutover Test for Default Media Type"
+created_at: 2014-03-05
+author_name: jasonrudolph
+---
+
+In January, we announced an [upcoming change to the default media type][2014-01-announcement]. To help developers assess the impact of that change before it becomes permanent, we're performing a [24-hour cutover test next week][cutover-test-announcement].
+
+From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will [respond with the v3 media type by default][what's-changing]. (See the [start time for the cutover test in your time zone][start-time].)
+
+Follow [@GitHubAPI][] to receive updates before and after the test.
+
+Please see the [original announcement][2014-01-announcement] for full details. If you have any questions, please [get in touch][contact].
+
+[@GitHubAPI]: https://twitter.com/GitHubAPI
+[2014-01-announcement]: /changes/2014-01-07-upcoming-change-to-default-media-type/
+[contact]: https://github.com/contact?form[subject]=Upcoming+change+to+default+API+media+type
+[cutover-test-announcement]: /changes/2014-01-07-upcoming-change-to-default-media-type/#cutover-test
+[start-time]: http://www.timeanddate.com/worldclock/fixedtime.html?iso=20140312T00&p1=1440
+[what's-changing]: /changes/2014-01-07-upcoming-change-to-default-media-type/#whats-changing
diff --git a/content/v3.md b/content/v3.md
@@ -571,5 +571,44 @@ A link that looks like this:
   ["url1", {:rel => "next"}],
   ["url2", {:rel => "foo", :bar => "baz"}]] %>
 
+## Timezones
+
+Some requests allow for specifying timestamps or generate timestamps with time
+zone information. We apply the following rules, in order of priority, to
+determine timezone information for API calls.
+
+#### Explicitly provide 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](/v3/git/commits).
+
+These timestamps look something like `2014-02-27T15:05:06+01:00`. Also see
+[this example](http://developer.github.com/v3/git/commits/#example-input) for
+how these timestamps can be specified.
+
+#### Using the `Time-Zone` header
+
+It is possible to supply a `Time-Zone` header which defines a timezone according
+to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+    $ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/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](/v3/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.
+
+#### Using the last known timezone for the user
+
+If no `Time-Zone` header is specified and you make an authenticated call to the
+API, we use the last known timezone for the authenticated user. The last know
+timezone is updated whenever you browse the GitHub.com website.
+
+#### UTC
+
+If the steps above don't result in any information, we use UTC as the timezone
+to create the git commit.
+
 [support]: https://github.com/contact?form[subject]=APIv3
 [pagination-guide]: /guides/traversing-with-pagination
diff --git a/content/v3/issues.md b/content/v3/issues.md
@@ -31,7 +31,7 @@ List all issues for a given organization for the authenticated user:
 Name | Type | Description
 -----|------|--------------
 `filter`|`string`| Indicates which sorts of issues to return. Can be one of:<br/>* `assigned`: Issues assigned to you<br/>* `created`: Issues created by you<br/>* `mentioned`: Issues mentioning you<br/>* `subscribed`: Issues you're subscribed to updates for<br/>* `all`: All issues the authenticated user can see, regardless of participation or creation<br/> Default: `assigned`
-`state`|`string`| Indicates the state of the issues to return. Can be either `open` or `closed`. Default: `open`
+`state`|`string`| Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`. Default: `open`
 `labels`|`string`| A list of comma separated label names.  Example: `bug,ui,@high`
 `sort`|`string`|  What to sort results by. Can be either `created`, `updated`, `comments`. Default: `created`
 `direction`|`string`| The direction of the sort. Can be either `asc` or `desc`. Default: `desc`
@@ -51,7 +51,7 @@ Name | Type | Description
 Name | Type | Description
 -----|------|--------------
 `milestone`|`integer` or `string`| If an `integer` is passed, it should refer to a milestone number. If the string `*` is passed, issues with any milestone are accepted. If the string `none` is passed, issues without milestones are returned. Default: `*`
-`state`|`string`| Indicates the state of the issues to return. Can be either `open` or `closed`. Default: `open`
+`state`|`string`| Indicates the state of the issues to return. Can be either `open`, `closed`, or `all`. Default: `open`
 `assignee`|`string`| Can be the name of a user. Pass in `none` for issues with no assigned user, and `*` for issues assigned to any user. Default: `*`
 `creator`|`string`| The user that created the issue.
 `mentioned`|`string`| A user that's mentioned in the issue.
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -183,6 +183,12 @@ Name | Description
 `read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
 `write:repo_hook`| Grants read, write, and ping access to hooks in public or private repositories.
 `admin:repo_hook`| Grants read, write, ping, and delete access to hooks in public or private repositories.
+`read:org`| Read-only access to organization, teams, and membership.
+`write:org`| Publicize and unpublicize organization membership.
+`admin:org`| Fully manage organization, teams, and memberships.
+`read:public_key`| List and view details for public keys.
+`write:public_key`| Create, list, and view details for public keys.
+`admin:public_key`| Fully manage public keys.
 
 NOTE: Your application can request the scopes in the initial redirection. You
 can specify multiple scopes by separating them with a comma:
@@ -192,76 +198,6 @@ can specify multiple scopes by separating them with a comma:
       scope=user,public_repo
 
 ## Common errors for the authorization request
-<<<<<<< HEAD
-
-There are a few things that can go wrong in the process of obtaining an
-OAuth token for a user. In the initial authorization request phase,
-these are some errors you might see:
-
-### Application Suspended
-
-If the OAuth application you set up has been suspended (due to reported
-abuse, spam, or a mis-use of the API), GitHub will redirect to the
-registered callback URL with the following parameters summerizing the
-error:
-
-    http://your-application.com/callback?error=application_suspended
-
-Please contact [support](https://github.com/contact) to solve issues
-with suspended applications.
-
-### Redirect URI mismatch
-
-If you provide a redirect_uri that doesn't match what you've registered
-with your application, GitHub will redirect to the registered callback
-URL with the following parameters summerizing the error:
-
-    http://your-application.com/callback?error=redirect_uri_mismatch
-
-To correct this error, either provide a redirect_uri that matches what
-you registered or leave out this parameter to use the default one
-registered with your application.
-
-### Access denied
-
-If the user rejects access to your application, GItHub will redirect to
-the registered callback URL with the following parameters summerizing
-the error:
-
-    http://your-application.com/callback?error=access_denied
-
-There's nothing you can do here as users are free to choose not to use
-your application. More often that not, users will just close the window
-or press back in their browser, so it is likely that you'll never see
-this error.
-
-## Common errors for the access token request
-
-In the second phase of exchanging a code for an access token, there are
-an additional set of errors that can occur. The format of these
-responses is determined by the accept header you pass. The following
-examples only show JSON responses.
-
-### Invalid client credentials
-
-If the client\_id and or client\_secret you pass are incorrect you will
-receive this error response.
-
-<%= json :error => :invalid_client_credentials %>
-
-To solve this error, go back and make sure you have the correct
-credentials for your oauth application. Double check the `client_id` and
-`client_secret` to make sure they are correct and being passed correctly
-to GitHub.
-
-### Bad verification code
-
-If the verification code you pass is incorrect, expired, or doesn't
-match what you received in the first request for authorization you will
-receive this error.
-
-<%= json :error => :bad_verification_code %>
-=======
 
 There are a few things that can go wrong in the process of obtaining an
 OAuth token for a user. In the initial authorization request phase,
@@ -351,6 +287,8 @@ registered with your application.
 
 ### Bad verification code
 
+<%= json :add_scopes => ['repo'], :note => 'admin script' %>
+
 If the verification code you pass is incorrect, expired, or doesn't
 match what you received in the first request for authorization you will
 receive this error.
@@ -360,11 +298,10 @@ receive this error.
          :error_uri         => "http://developer.github.com/v3/oauth/#bad-verification-code"
 %>
 
->>>>>>> master
-
 To solve this error, start the [OAuth process over from the beginning](#redirect-users-to-request-github-access)
 and get a new code.
 
 [oauth changes blog]: /changes/2013-10-04-oauth-changes-coming/
 [basics auth guide]: /guides/basics-of-authentication/
 [deployments]: /v3/repos/deployments
+[public keys]: /v3/users/keys/
diff --git a/content/v3/orgs/teams.md b/content/v3/orgs/teams.md
@@ -205,7 +205,9 @@ organization, you get:
 ## Remove team repository {#remove-team-repo}
 
 In order to remove a repository from a team, the authenticated user must be an
-owner of the org that the team is associated with.
+owner of the org that the team is associated with. Also, since the Owners team
+always has access to all repositories in the organization, repositories cannot
+be removed from the Owners team.
 NOTE: This does not delete the repository, it just removes it from the team.
 
     DELETE /teams/:id/repos/:owner/:repo
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
@@ -38,9 +38,11 @@ Name | Description
 
 Name | Type | Description
 -----|------|--------------
-`state`|`string` | Either `open` or `closed` to filter by state. Default: `open`
+`state`|`string` | Either `open`, `closed`, or `all` to filter by state. Default: `open`
 `head`|`string` | Filter pulls by head user and branch name in the format of `user:ref-name`. Example: `github:new-script-format`.
 `base`|`string` | Filter pulls by base branch name. Example: `gh-pages`.
+`sort`|`string`|  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). Default: `created`
+`direction`|`string`| The direction of the sort. Can be either `asc` or `desc`. Default: `desc`
 
 
 ### Response
diff --git a/content/v3/repos.md b/content/v3/repos.md
diff --git a/content/v3/repos/keys.md b/content/v3/repos/keys.md
diff --git a/content/v3/users/keys.md b/content/v3/users/keys.md
diff --git a/content/webhooks/creating/index.md b/content/webhooks/creating/index.md
diff --git a/lib/resources.rb b/lib/resources.rb
