From dd38b89f7638fda685c6f7dfc8813147f158a884 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Thu, 30 Jun 2016 18:23:43 -0700 Subject: [PATCH 01/29] Use a more descriptive type for oauth.allow_signup If it's true or false, it's a boolean. --- content/v3/oauth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/oauth.md b/content/v3/oauth.md index 435cd815f8..1555d954d7 100644 --- a/content/v3/oauth.md +++ b/content/v3/oauth.md @@ -37,7 +37,7 @@ Name | Type | Description `redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). `scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope. `state`|`string` | An unguessable random string. It is used to protect against cross-site request forgery attacks. -`allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. +`allow_signup`|`boolean` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. ### 2. GitHub redirects back to your site From 2f6db25b21b85a70b69b3e4c3ef8b2dd7bc2796f Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 11 Jul 2016 18:33:26 -0700 Subject: [PATCH 02/29] Sync changes from upstream repository --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index b0842a92cb..49c438d8e5 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,18 @@ Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you s [nanoc]: http://nanoc.ws/ +### Enterprise + +To generate the `/enterprise/` versions, use `script/enterprise-backport`: + +``` sh +$ script/enterprise-backport 2.6 +$ mv -f enterprise output +$ script/server +``` + +The above will need to be repeated anytime changes are made to `/enterprise` versioned documentation. + ## Styleguide Not sure how to structure the docs? Here's what the structure of the From b565e2f444c54c00f34e4f257daaf22f4e3a9e47 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 14:22:12 -0700 Subject: [PATCH 03/29] Sync changes from upstream repository --- content/v3/misc.md | 4 ++++ content/v3/rate_limit.md | 4 ++++ content/v3/search.md | 4 ++++ layouts/sidebar.html | 2 ++ 4 files changed, 14 insertions(+) diff --git a/content/v3/misc.md b/content/v3/misc.md index 01a57d22a2..7fefcbb369 100644 --- a/content/v3/misc.md +++ b/content/v3/misc.md @@ -33,11 +33,15 @@ organization's [GitHub Enterprise](https://enterprise.github.com/) installation. {% endif %} +{% if page.version == 'dotcom' %} + ## [Rate Limit][] The [Rate Limit API][Rate Limit] lets you check your current rate limit status at any time. +{% endif %} + ## [Licenses][] The [Licenses API][Licenses] returns information about open source licenses or under what license, if any a given project is distributed. diff --git a/content/v3/rate_limit.md b/content/v3/rate_limit.md index b19c878ecb..cb27f21b3b 100644 --- a/content/v3/rate_limit.md +++ b/content/v3/rate_limit.md @@ -2,6 +2,8 @@ title: Rate Limit --- +{% if page.version == 'dotcom' %} + # Rate Limit The overview documentation describes the [rate limit rules](/v3/#rate-limiting). @@ -49,3 +51,5 @@ version of the API. If you're writing new API client code (or updating your existing code), you should use the `"core"` object instead of the `"rate"` object. The `"core"` object contains the same information that is present in the `"rate"` object. + +{% endif %} diff --git a/content/v3/search.md b/content/v3/search.md index 05ca2781c1..39df7d1f6e 100644 --- a/content/v3/search.md +++ b/content/v3/search.md @@ -25,6 +25,8 @@ is a computed value representing the relevance of an item relative to the other items in the result set. Multiple factors are combined to boost the most relevant item to the top of the result list. +{% if page.version == 'dotcom' %} + ### Rate limit The Search API has a custom rate limit. For requests using [Basic @@ -36,6 +38,8 @@ to make up to 10 requests per minute. See the [rate limit documentation](/v3/#rate-limiting) for details on determining your current rate limit status. +{% endif %} + ### Timeouts and incomplete results To keep the Search API fast for everyone, we limit how long any individual query diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 31ce45610c..fe51837c49 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -69,7 +69,9 @@

Licenses
  • Markdown
  • Meta
    • + <% if @item[:version] == 'dotcom' %>
  • Rate Limit
    • + <% end %>
  • From 3ca3f26538087e4a976e040f81dae6f88dc7992d Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 14:53:22 -0700 Subject: [PATCH 04/29] Sync changes from upstream repository --- ...nding-multiple-assignees-preview-period.md | 13 ++++ content/v3/issues.md | 76 +------------------ content/v3/issues/assignees.md | 29 ------- content/v3/versions.md | 5 ++ 4 files changed, 22 insertions(+), 101 deletions(-) create mode 100644 content/changes/2016-7-1-ending-multiple-assignees-preview-period.md diff --git a/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md b/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md new file mode 100644 index 0000000000..13f6fc318b --- /dev/null +++ b/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md @@ -0,0 +1,13 @@ +--- +title: Multiple Assignees API is now official +author_name: nakajima +--- + +We're making [Multiple Assignees][blog-post] part of the official GitHub API. + +During the preview period you needed to provide the `application/vnd.github.cerberus-preview` preview media type in the `Accept` header to opt-in to the changes. Now that the preview period has ended, you no longer need to specify this custom media type. + +If you have any questions or feedback, please [get in touch with us][contact]! + +[blog-post]: /changes/2016-5-27-multiple-assignees/ +[contact]: https://github.com/contact?form[subject]=Multiple+Assignees+API diff --git a/content/v3/issues.md b/content/v3/issues.md index e2f9b9f5f4..59e7f99a29 100644 --- a/content/v3/issues.md +++ b/content/v3/issues.md @@ -159,33 +159,18 @@ Name | Type | Description -----|------|-------------- `title`|`string` | **Required**. The title of the issue. `body`|`string` | The contents of the issue. -`assignee`|`string` | Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise._ +`assignee`|`string` | Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise. **This field is [deprecated](https://developer.github.com/v3/versions/#v3-deprecations).**_ `milestone`|`integer` | The `number` of the milestone to associate this issue with. _NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. _NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise._ `assignees`|`array` of `strings` | Logins for Users to assign to this issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ -{{#tip}} - - - -The `assignees` parameter is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -The `assignees` key will only be accepted in issue payloads if this header is passed. - -{{/tip}} - #### Example <%= json \ :title => "Found a bug", :body => "I'm having a problem with this.", :assignee => "octocat", + :assignees => [get_resource(:user)], :milestone => 1, :labels => %w(bug) %> @@ -195,25 +180,6 @@ The `assignees` key will only be accepted in issue payloads if this header is pa <%= headers 201, :Location => get_resource(:full_issue)['url'] %> <%= json :full_issue %> -{% if page.version == 'dotcom' %} -#### Multiple Assignees - -{{#tip}} - - - - An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. - Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview - - The `assignees` key will be an Array of Users who are assigned to the issue. - -{{/tip}} -{% endif %} - ## Edit an issue Issue owners and users with push access can edit an issue. @@ -226,34 +192,19 @@ Name | Type | Description -----|------|-------------- `title`|`string` | The title of the issue. `body`|`string` | The contents of the issue. -`assignee`|`string` | Login for the user that this issue should be assigned to. +`assignee`|`string` | Login for the user that this issue should be assigned to. **This field is [deprecated](https://developer.github.com/v3/versions/#v3-deprecations).** `state`|`string` | State of the issue. Either `open` or `closed`. `milestone`|`integer` | The `number` of the milestone to associate this issue with or `null` to remove current. _NOTE: Only users with push access can set the milestone for issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. Pass one or more Labels to _replace_ the set of Labels on this Issue. Send an empty array (`[]`) to clear all Labels from the Issue. _NOTE: Only users with push access can set labels for issues. Labels are silently dropped otherwise._ `assignees`|`array` of `strings` | Logins for Users to assign to this issue. Pass one or more user logins to _replace_ the set of assignees on this Issue. .Send an empty array (`[]`) to clear all assignees from the Issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ -{{#tip}} - - - -The `assignees` parameter is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -The `assignees` key will only be present in issue payloads if this header is passed. - -{{/tip}} - #### Example <%= json \ :title => "Found a bug", :body => "I'm having a problem with this.", :assignee => "octocat", + :assignees => [get_resource(:user)], :milestone => 1, :state => "open", :labels => %w(bug) @@ -264,25 +215,6 @@ The `assignees` key will only be present in issue payloads if this header is pas <%= headers 200 %> <%= json :full_issue %> -{% if page.version == 'dotcom' %} -#### Multiple Assignees - -{{#tip}} - - - - An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. - Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview - - The `assignees` key will be an Array of Users who are assigned to the issue. - -{{/tip}} -{% endif %} - {% if page.version == 'dotcom' or page.version >= 2.6 %} ## Lock an issue diff --git a/content/v3/issues/assignees.md b/content/v3/issues/assignees.md index 139a98f98c..4d0c1a59a0 100644 --- a/content/v3/issues/assignees.md +++ b/content/v3/issues/assignees.md @@ -38,21 +38,6 @@ Otherwise a `404` status code is returned. ## Add assignees to an Issue -{{#tip}} - - - -This endpoint is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -{{/tip}} - - This call adds the users passed in the `assignees` key (as their logins) to the issue. POST /repos/:owner/:repo/issues/:number/assignees @@ -68,20 +53,6 @@ This call adds the users passed in the `assignees` key (as their logins) to the ## Remove assignees from an Issue -{{#tip}} - - - -This endpoint is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -{{/tip}} - This call removes the users passed in the `assignees` key (as their logins) from the issue. DELETE /repos/:owner/:repo/issues/:number/assignees diff --git a/content/v3/versions.md b/content/v3/versions.md index e9112368d7..53c7cf6f33 100644 --- a/content/v3/versions.md +++ b/content/v3/versions.md @@ -145,6 +145,11 @@ The recommendations below will help you prepare your application for the next ma Recommendation: This attribute no longer dictates the permission a team has on its repositories; it only dictates the default permission that the [Add or update team repository](/v3/orgs/teams/#add-or-update-team-repository) API will use for requests where no `permission` attribute is specified. To change the permission level for every repository on a team, use the [List team repositories](/v3/orgs/teams/#list-team-repos) API to list all of the team's repositories, and then use the [Add or update team repository](/v3/orgs/teams/#add-or-update-team-repository) with a `permission` attribute to update each repository's permission separately. +1. Issue attribute: assignee + + Recommendation: Use the [`assignees`](https://developer.github.com/v3/issues/#create-an-issue) key instead, since issues can have more than one assignee. Alternatively, you can use the + [assignees](https://developer.github.com/v3/issues/assignees/) endpoints. + # beta (Deprecated) From 86a03bf66a38195703fabf3c9d7760ec49e25ece Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 23:09:21 -0700 Subject: [PATCH 05/29] Sync changes from upstream repository --- ....md => 2016-07-12-ending-multiple-assignees-preview-period.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/changes/{2016-7-1-ending-multiple-assignees-preview-period.md => 2016-07-12-ending-multiple-assignees-preview-period.md} (100%) diff --git a/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md b/content/changes/2016-07-12-ending-multiple-assignees-preview-period.md similarity index 100% rename from content/changes/2016-7-1-ending-multiple-assignees-preview-period.md rename to content/changes/2016-07-12-ending-multiple-assignees-preview-period.md From 53a38f9dbd20a99c90ebac1b05d332c3b0168fa8 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 14 Jul 2016 09:22:46 -0700 Subject: [PATCH 06/29] Sync changes from upstream repository --- README.md | 8 +++----- content/v3.md | 14 ++++++++++++-- content/v3/search.md | 8 ++++---- lib/resources.rb | 6 ++++-- script/server | 10 +++++++++- 5 files changed, 32 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 49c438d8e5..7a1e3bfcc9 100644 --- a/README.md +++ b/README.md @@ -48,15 +48,13 @@ Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you s ### Enterprise -To generate the `/enterprise/` versions, use `script/enterprise-backport`: +To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: ``` sh -$ script/enterprise-backport 2.6 -$ mv -f enterprise output -$ script/server +$ script/server 2.6 ``` -The above will need to be repeated anytime changes are made to `/enterprise` versioned documentation. +Note that live reloading is not available for Enterprise documentation. ## Styleguide diff --git a/content/v3.md b/content/v3.md index d73a059c18..a387737d67 100644 --- a/content/v3.md +++ b/content/v3.md @@ -32,9 +32,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/users/octocat/orgs > Status: 200 OK > ETag: "a00049ba79152d03380c34652f2cb612" > X-GitHub-Media-Type: github.v3 +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4987 > X-RateLimit-Reset: 1350085394 +{% endif %} > Content-Length: 5 > Cache-Control: max-age=0, private, must-revalidate > X-Content-Type-Options: nosniff @@ -504,9 +506,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 200 OK > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"' > HTTP/1.1 304 Not Modified @@ -515,9 +519,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 304 Not Modified > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT" > HTTP/1.1 304 Not Modified @@ -525,9 +531,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H "If-Modified-Sin > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 304 Not Modified > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} ``` ## Cross Origin Resource Sharing @@ -545,7 +553,7 @@ Here's a sample request sent from a browser hitting $ curl -i {{ site.data.variables.product.api_url_pre }} -H "Origin: http://example.com" HTTP/1.1 302 Found Access-Control-Allow-Origin: * -Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval +Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, {% if page.version == 'dotcom' %}X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,{% endif %} X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval Access-Control-Allow-Credentials: true ``` @@ -557,7 +565,7 @@ HTTP/1.1 204 No Content Access-Control-Allow-Origin: * Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE -Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval +Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, {% if page.version == 'dotcom' %}X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,{% endif %} X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval Access-Control-Max-Age: 86400 Access-Control-Allow-Credentials: true ``` @@ -576,9 +584,11 @@ $ curl https://api.github.com?callback=foo > /**/foo({ > "meta": { > "status": 200, +{% if page.version == 'dotcom' %} > "X-RateLimit-Limit": "5000", > "X-RateLimit-Remaining": "4966", > "X-RateLimit-Reset": "1372700873", +{% endif %} > "Link": [ // pagination headers and other links > ["https://api.github.com?page=2", {"rel": "next"}] > ] diff --git a/content/v3/search.md b/content/v3/search.md index 39df7d1f6e..bfdefdd175 100644 --- a/content/v3/search.md +++ b/content/v3/search.md @@ -97,7 +97,7 @@ repositories where the primary language is Assembly. We're sorting by stars in descending order, so that the most popular repositories appear first in the search results. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels{% if page.version == 'dotcom' %}, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:repo_search_v3_results) %> ### Highlighting Repository Search Results @@ -186,7 +186,7 @@ Here, we're searching for the keyword `addClass` within a file's contents. We're making sure that we're only looking in files where the language is JavaScript. And we're scoping the search to the `repo:jquery/jquery` repository. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:code_search_v3_results) %> ### Highlighting Code Search Results @@ -289,7 +289,7 @@ that's labeled as `bug`. The search runs across repositories whose primary language is Python. We’re sorting by creation date in ascending order, so that the oldest issues appear first in the search results. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:issue_search_v3_results) %> ### Highlighting Issue Search Results @@ -361,7 +361,7 @@ Imagine you're looking for a list of popular users. You might try out this query Here, we're looking at users with the name Tom. We're only interested in those with more than 42 repositories, and only if they have over 1,000 followers. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:user_search_v3_results) %> ### Highlighting User Search Results diff --git a/lib/resources.rb b/lib/resources.rb index caa1276fee..8d3078aaec 100644 --- a/lib/resources.rb +++ b/lib/resources.rb @@ -67,8 +67,10 @@ def headers(status, head = {}) end end - lines << "X-RateLimit-Limit: 5000" unless head.has_key?('X-RateLimit-Limit') - lines << "X-RateLimit-Remaining: 4999" unless head.has_key?('X-RateLimit-Remaining') + unless @config[:version] != 'dotcom' + lines << "X-RateLimit-Limit: 5000" unless head.has_key?('X-RateLimit-Limit') + lines << "X-RateLimit-Remaining: 4999" unless head.has_key?('X-RateLimit-Remaining') + end %(``` headers\n#{lines.join("\n")}\n```\n) end diff --git a/script/server b/script/server index 33707763fe..d0365c2e66 100755 --- a/script/server +++ b/script/server @@ -3,4 +3,12 @@ ulimit -n 2048 script/bootstrap -DEV_MODE=true npm run gulp + +if [ -z "$1" ] + then + DEV_MODE=true npm run gulp + else + script/enterprise-backport $1 + mv -f enterprise output + npm run gulp server +fi From 9dd526708d48ea0f6d158339e11e359f985a67ba Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 19 Jul 2016 01:59:34 -0700 Subject: [PATCH 07/29] Sync changes from upstream repository --- content/changes/2016-07-06-github-pages-preiew-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preiew-api.md index 2c8374b29d..ab14cbee46 100644 --- a/content/changes/2016-07-06-github-pages-preiew-api.md +++ b/content/changes/2016-07-06-github-pages-preiew-api.md @@ -13,7 +13,7 @@ You can now manually request a build of your GitHub Pages site without needing t curl "https://api.github.com/repos/github/developer.github.com/pages/builds" \ -X POST -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.mister-fantstic-preview" \ + -H "Accept: application/vnd.github.mister-fantastic-preview" \ ``` #### Retrieving a site's URL @@ -27,7 +27,7 @@ For example, to request the HTML URL: ``` command-line curl "https://api.github.com/repos/github/developer.github.com/pages" \ -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.mister-fantstic-preview" \ + -H "Accept: application/vnd.github.mister-fantastic-preview" \ ``` #### How can I try it? From 09675d035af2ec51ba44cf3be981f8eb40cdfbd9 Mon Sep 17 00:00:00 2001 From: Chao Date: Thu, 21 Jul 2016 15:16:36 -0400 Subject: [PATCH 08/29] fix date format. fix date format. --- lib/responses/admin.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/responses/admin.rb b/lib/responses/admin.rb index 6a8235cac3..340e6984f4 100644 --- a/lib/responses/admin.rb +++ b/lib/responses/admin.rb @@ -67,7 +67,7 @@ module Responses "seats_available" => 84, "kind" => "standard", "days_until_expiration" => 365, - "expire_at" => "2016/02/06 12:41:52 -0600" + "expire_at" => "2016-02-06T12:41:52-06:00" } INDEXING_SUCCESS ||= { From 95b05a946e09a259f59d6153c41d0cf4204d3a4c Mon Sep 17 00:00:00 2001 From: Hubot Date: Sun, 24 Jul 2016 04:39:07 -0700 Subject: [PATCH 09/29] Sync changes from upstream repository --- content/v3/gists.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/gists.md b/content/v3/gists.md index 1038a72acb..0f73102306 100644 --- a/content/v3/gists.md +++ b/content/v3/gists.md @@ -48,7 +48,7 @@ Name | Type | Description List all public gists sorted by most recently updated to least recently updated. -Note: With pagination, you can fetch up to 200 [pages](/v3/#pagination). +Note: With [pagination](/v3/#pagination), you can fetch up to 3000 gists. For example, you can fetch 100 pages with 30 gists per page or 30 pages with 100 gists per page. GET /gists/public From 22879a2512dca092867bdccc88a2af36d3e572db Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 29 Jul 2016 13:29:08 -0700 Subject: [PATCH 10/29] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ++++++++++++++++++ content/v3/enterprise/pre_receive_hooks.md | 110 ++++++++++ content/v3/orgs/pre_receive_hooks.md | 83 ++++++++ content/v3/repos/pre_receive_hooks.md | 88 ++++++++ layouts/sidebar.html | 10 + lib/responses/pre_receive.rb | 136 ++++++++++++ 6 files changed, 620 insertions(+) create mode 100644 content/v3/enterprise/pre_receive_environments.md create mode 100644 content/v3/enterprise/pre_receive_hooks.md create mode 100644 content/v3/orgs/pre_receive_hooks.md create mode 100644 content/v3/repos/pre_receive_hooks.md create mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md new file mode 100644 index 0000000000..ac12fe2409 --- /dev/null +++ b/content/v3/enterprise/pre_receive_environments.md @@ -0,0 +1,193 @@ +--- +title: Pre-receive Environments +--- + +# Pre-receive Environments + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. *It is only available to [authenticated](/v3/#authentication) site administrators.* Normal users will receive a `404` response if they try to access it. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Environment + +| Name | Type | Description | +|-----------------------|-----------|----------------------------------------------------------------------------| +| `name` | `string` | The name of the environment as displayed in the UI. | +| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | +| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | +| `download` | `object` | This environment's download status. | +| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | + +### Pre-receive Environment Download + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + + +## Get a single pre-receive environment + + GET /admin/pre-receive-environments/:id + +<%= headers 200 %> +<%= json :pre_receive_environment %> + +## List pre-receive environments + + GET /admin/pre_receive_environments + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_environments %> + +## Create a pre-receive environment + + POST /admin/pre_receive_environments + +### Parameters + +| Name | Type | Description | +|-------------|----------|-------------------------------------------------------------------------| +| `name` | `string` | **Required**. The new pre-receive environment's name. | +| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | + +<%= json \ + :name => 'DevTools Hook Env', + :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' +%> + +### Response + +<%= headers 201 %> +<%= json :pre_receive_environment_create %> + +## Edit a pre-receive environment + + PATCH /admin/pre_receive_environments/:id + +### Parameters + +| Name | Type | Description | +|-------------|----------|-----------------------------------------------------------| +| `name` | `string` | This pre-receive environment's new name. | +| `image_url` | `string` | URL from which to download a tarball of this environment. | + +### Response +<%= headers 200 %> +<%= json :pre_receive_environment %> + +#### Client Errors + +If you attempt to modify the default environment, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +## Delete a pre-receive environment + + DELETE /admin/pre_receive_environments/:id + +### Response + +<%= headers 204 %> + +#### Client Errors + +If you attempt to delete an environment that cannot be deleted, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Cannot delete environment that has hooks_ +- _Cannot delete environment when download is in progress_ + +## Get a pre-receive environment's download status + +In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. + + GET /admin/pre-receive-environments/:id/downloads/latest + +<%= headers 200 %> +<%= json :pre_receive_environment_download_2 %> + +### Object attributes + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + +## Trigger a pre-receive environment download + +Triggers a new download of the environment tarball from the environment's `image_url`. When the download is finished, the newly downloaded tarball will overwrite the existing environment. + + POST /admin/pre_receive_environments/:id/downloads + +### Response + +<%= headers 202 %> +<%= json :pre_receive_environment_download %> + +#### Client Errors + +If a download cannot be triggered, you will get a reponse like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Can not start a new download when a download is in progress' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Can not start a new download when a download is in progress_ + diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md new file mode 100644 index 0000000000..876f242bbd --- /dev/null +++ b/content/v3/enterprise/pre_receive_hooks.md @@ -0,0 +1,110 @@ +--- +title: Pre-receive Hooks +--- + +# Pre-receive Hooks + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Hooks API allows you to create, list, update and delete +pre-receive hooks. *It is only available to +[authenticated](/v3/#authentication) site administrators.* Normal users +will receive a `404` response if they try to access it. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Hook + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `script` | `string` | The script that the hook runs. | +| `script_repository` | `object` | The GitHub repository where the script is kept. | +| `environment` | `object` | The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +## Get a single pre-receive hook + + GET /admin/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook %> + +## List pre-receive hooks + + GET /admin/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks %> + +## Create a pre-receive hook + + POST /admin/pre-receive-hooks + +### Parameters + +| Name | Type | Description | +|----------------------------------|-----------|----------------------------------------------------------------------------------| +| `name` | `string` | **Required** The name of the hook. | +| `script` | `string` | **Required** The script that the hook runs. | +| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | +| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | + +<%= json \ + :name => "Check Commits", + :script => "scripts/commit_check.sh", + :enforcement => "disabled", + :allow_downstream_configuration => false, + :script_repository => { :full_name => "DevIT/hooks" }, + :environment => { :id => 2 } +%> + +### Response +<%= headers 201 %> +<%= json :pre_receive_hook %> + +## Edit a pre-receive hook + + PATCH /admin/pre_receive_hooks/:id + +<%= json \ + :name => "Check Commits", + :environment => { :id => 1 }, + :allow_downstream_configuration => true +%> + +### Response +<%= headers 200 %> +<%= json :pre_receive_hook_update %> + +## Delete a pre-receive hook + + DELETE /admin/pre_receive_hooks/:id + +### Response + +<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md new file mode 100644 index 0000000000..7d3afc0bd4 --- /dev/null +++ b/content/v3/orgs/pre_receive_hooks.md @@ -0,0 +1,83 @@ +--- +title: Organization Pre-receive Hooks +--- + +# Organization Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Organization Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to an organization. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this endpoint or this hook's global +configuration. Only site admins are able to access the global configuration. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +organization as well as any disabled hooks that can be configured at the +organization level. Globally disabled pre-receive hooks that do not allow +downstream configuration are not listed. + + GET /orgs/:org/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_org %> + +## Get a single pre-receive hook + + GET /orgs/:org:pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the org level, you can set +`enforcement` and `allow_downstream_configuration` + + PATCH /orgs/:org/pre-receive-hooks/:id + +<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_org_update %> + +## Remove enforcment overrides for a pre-receive hook + +Removes any overrides for this hook at the org level for this org. + + DELETE /orgs/:org/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md new file mode 100644 index 0000000000..2eef1d9459 --- /dev/null +++ b/content/v3/repos/pre_receive_hooks.md @@ -0,0 +1,88 @@ +--- +title: Repository Pre-receive Hooks +--- + +# Repository Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + + +{:toc} + +The Repository Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to a repository. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|---------------------|----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this repository, it's organization +owner or global configuration. Authorization to access the endpoint at +`configuration_url` is determined at the owner or site admin level. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +repository as well as any disabled hooks that are allowed to be enabled +at the repository level. Pre-receive hooks that are disabled at a higher +level and are not configurable will not be listed. + + GET /repos/:owner/:repo/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_repo %> + +## Get a single pre-receive hook + + GET /repos/:owner/:repo/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` + + PATCH /repos/:owner/:repo/pre-receive-hooks/:id + +<%= json :enforcement => "enabled" %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_repo_update %> + +## Remove enforcement overrides for a pre-receive hook + +Deletes any overridden enforcement on this repository for the specified +hook. + + DELETE /repos/:owner/:repo/pre-receive-hooks/:id + +### Response + +Responds with effective values inherited from owner and/or global level. + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index fe51837c49..b36458f202 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,6 +80,9 @@

    Members

  • Teams
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -116,6 +119,9 @@

    Statistics

  • Statuses
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -147,6 +153,10 @@

    LDAP

  • License
  • Management Console
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Environments
    • +
  • Pre-receive Hooks
    • + <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb new file mode 100644 index 0000000000..6ccf0a4ab9 --- /dev/null +++ b/lib/responses/pre_receive.rb @@ -0,0 +1,136 @@ +module GitHub + module Resources + module Responses + URL_OPTIONS = { + :base_api_url => "https://github.example.com/api/v3", + :base_url => "https://github.example.com" + } + + def self.options_to_output(options, keys_to_use) + keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } + end + + def self.pre_receive_environment_download(options = {}) + options = URL_OPTIONS.merge( + :id => 3, + :downloaded_at => '2016-05-26T07:42:53-05:00', + :state => 'success', + :message => nil + ).merge options + options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" + options_to_output options, %w(url state downloaded_at message) + end + + def self.pre_receive_environment(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Default', + :image_url => 'githubenterprise://internal', + :created_at => '2016-05-20T11:35:45-05:00', + :hooks_count => 1, + :download_options => {}, + :default_environment => true + ).merge options + options.update( + :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", + :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", + :download => pre_receive_environment_download(options.merge options[:download_options]) + ) + options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) + end + + def self.pre_receive_script_repository(options = {}) + options = URL_OPTIONS.merge( + :id => 595, + :full_name => "ExampleOrg/hooks", + ).merge options + options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" + options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output options, %w(id full_name url html_url) + end + + def self.pre_receive_hook(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Check Commits', + :script => 'scripts/commmit_check.sh', + :script_repository => { + :id => 595, + :full_name => "DevIT/hooks" + }, + :environment => PRE_RECEIVE_ENVIRONMENT, + :enforcement => "disabled", + :allow_downstream_configuration => false + ).merge options + options[:script_repository][:url] ||= + "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" + options[:script_repository][:html_url] ||= + "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) + end + + def self.pre_receive_hook_repo(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42" + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url)) + end + + def self.pre_receive_hook_org(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/admin/pre-receive-hooks/42", + :allow_downstream_configuration => true + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) + end + + PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ + :id => 2, + :name => "DevTools Hook Env", + :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", + :default_environment => false + }) + + PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ + "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) + }) + + PRE_RECEIVE_ENVIRONMENTS ||= [ + pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), + PRE_RECEIVE_ENVIRONMENT + ] + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= + pre_receive_environment_download :state => 'not_started', + :downloaded_at => nil + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download + + PRE_RECEIVE_HOOK ||= pre_receive_hook + PRE_RECEIVE_HOOKS ||= [pre_receive_hook] + PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment + + PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo + + PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] + + PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", + :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" + + PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org + PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] + PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42", + :allow_downstream_configuration => false + + end + end +end From 00da7b85ebeb4313551b7affa0e1f51b80f47a38 Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 1 Aug 2016 12:58:31 -0700 Subject: [PATCH 11/29] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ------------------ content/v3/enterprise/pre_receive_hooks.md | 110 ---------- content/v3/orgs/pre_receive_hooks.md | 83 -------- content/v3/repos/pre_receive_hooks.md | 88 -------- layouts/sidebar.html | 10 - lib/responses/pre_receive.rb | 136 ------------ 6 files changed, 620 deletions(-) delete mode 100644 content/v3/enterprise/pre_receive_environments.md delete mode 100644 content/v3/enterprise/pre_receive_hooks.md delete mode 100644 content/v3/orgs/pre_receive_hooks.md delete mode 100644 content/v3/repos/pre_receive_hooks.md delete mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md deleted file mode 100644 index ac12fe2409..0000000000 --- a/content/v3/enterprise/pre_receive_environments.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Pre-receive Environments ---- - -# Pre-receive Environments - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. *It is only available to [authenticated](/v3/#authentication) site administrators.* Normal users will receive a `404` response if they try to access it. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -### Pre-receive Environment - -| Name | Type | Description | -|-----------------------|-----------|----------------------------------------------------------------------------| -| `name` | `string` | The name of the environment as displayed in the UI. | -| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | -| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | -| `download` | `object` | This environment's download status. | -| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | - -### Pre-receive Environment Download - -| Name | Type | Description | -|-----------------|----------|---------------------------------------------------------| -| `state` | `string` | The state of the most recent download. | -| `downloaded_at` | `string` | The time when the most recent download started. | -| `message` | `string` | On failure, this will have any error messages produced. | - -Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. - - -## Get a single pre-receive environment - - GET /admin/pre-receive-environments/:id - -<%= headers 200 %> -<%= json :pre_receive_environment %> - -## List pre-receive environments - - GET /admin/pre_receive_environments - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_environments %> - -## Create a pre-receive environment - - POST /admin/pre_receive_environments - -### Parameters - -| Name | Type | Description | -|-------------|----------|-------------------------------------------------------------------------| -| `name` | `string` | **Required**. The new pre-receive environment's name. | -| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | - -<%= json \ - :name => 'DevTools Hook Env', - :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' -%> - -### Response - -<%= headers 201 %> -<%= json :pre_receive_environment_create %> - -## Edit a pre-receive environment - - PATCH /admin/pre_receive_environments/:id - -### Parameters - -| Name | Type | Description | -|-------------|----------|-----------------------------------------------------------| -| `name` | `string` | This pre-receive environment's new name. | -| `image_url` | `string` | URL from which to download a tarball of this environment. | - -### Response -<%= headers 200 %> -<%= json :pre_receive_environment %> - -#### Client Errors - -If you attempt to modify the default environment, you will get a response like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Cannot modify or delete the default environment' - }] -%> - -## Delete a pre-receive environment - - DELETE /admin/pre_receive_environments/:id - -### Response - -<%= headers 204 %> - -#### Client Errors - -If you attempt to delete an environment that cannot be deleted, you will get a response like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Cannot modify or delete the default environment' - }] -%> - -The possible error messages are: - -- _Cannot modify or delete the default environment_ -- _Cannot delete environment that has hooks_ -- _Cannot delete environment when download is in progress_ - -## Get a pre-receive environment's download status - -In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. - - GET /admin/pre-receive-environments/:id/downloads/latest - -<%= headers 200 %> -<%= json :pre_receive_environment_download_2 %> - -### Object attributes - -| Name | Type | Description | -|-----------------|----------|---------------------------------------------------------| -| `state` | `string` | The state of the most recent download. | -| `downloaded_at` | `string` | The time when the most recent download started. | -| `message` | `string` | On failure, this will have any error messages produced. | - -Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. - -## Trigger a pre-receive environment download - -Triggers a new download of the environment tarball from the environment's `image_url`. When the download is finished, the newly downloaded tarball will overwrite the existing environment. - - POST /admin/pre_receive_environments/:id/downloads - -### Response - -<%= headers 202 %> -<%= json :pre_receive_environment_download %> - -#### Client Errors - -If a download cannot be triggered, you will get a reponse like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Can not start a new download when a download is in progress' - }] -%> - -The possible error messages are: - -- _Cannot modify or delete the default environment_ -- _Can not start a new download when a download is in progress_ - diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md deleted file mode 100644 index 876f242bbd..0000000000 --- a/content/v3/enterprise/pre_receive_hooks.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Pre-receive Hooks ---- - -# Pre-receive Hooks - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -The Pre-receive Hooks API allows you to create, list, update and delete -pre-receive hooks. *It is only available to -[authenticated](/v3/#authentication) site administrators.* Normal users -will receive a `404` response if they try to access it. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -### Pre-receive Hook - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `script` | `string` | The script that the hook runs. | -| `script_repository` | `object` | The GitHub repository where the script is kept. | -| `environment` | `object` | The pre-receive environment where the script is executed. | -| `enforcement` | `string` | The state of enforcement for this hook. | -| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | - -Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -## Get a single pre-receive hook - - GET /admin/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook %> - -## List pre-receive hooks - - GET /admin/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks %> - -## Create a pre-receive hook - - POST /admin/pre-receive-hooks - -### Parameters - -| Name | Type | Description | -|----------------------------------|-----------|----------------------------------------------------------------------------------| -| `name` | `string` | **Required** The name of the hook. | -| `script` | `string` | **Required** The script that the hook runs. | -| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | -| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | -| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | -| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | - -<%= json \ - :name => "Check Commits", - :script => "scripts/commit_check.sh", - :enforcement => "disabled", - :allow_downstream_configuration => false, - :script_repository => { :full_name => "DevIT/hooks" }, - :environment => { :id => 2 } -%> - -### Response -<%= headers 201 %> -<%= json :pre_receive_hook %> - -## Edit a pre-receive hook - - PATCH /admin/pre_receive_hooks/:id - -<%= json \ - :name => "Check Commits", - :environment => { :id => 1 }, - :allow_downstream_configuration => true -%> - -### Response -<%= headers 200 %> -<%= json :pre_receive_hook_update %> - -## Delete a pre-receive hook - - DELETE /admin/pre_receive_hooks/:id - -### Response - -<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md deleted file mode 100644 index 7d3afc0bd4..0000000000 --- a/content/v3/orgs/pre_receive_hooks.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Organization Pre-receive Hooks ---- - -# Organization Pre-receive Hooks (Enterprise) - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -The Organization Pre-receive Hooks API allows you to view and modify -enforcement of the pre-receive hooks that are available to an organization. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this endpoint or this hook's global -configuration. Only site admins are able to access the global configuration. - -## List pre-receive hooks - -List all pre-receive hooks that are enabled or testing for this -organization as well as any disabled hooks that can be configured at the -organization level. Globally disabled pre-receive hooks that do not allow -downstream configuration are not listed. - - GET /orgs/:org/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks_org %> - -## Get a single pre-receive hook - - GET /orgs/:org:pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_org %> - -## Update pre-receive hook enforcement - -For pre-receive hooks which are allowed to be configured at the org level, you can set -`enforcement` and `allow_downstream_configuration` - - PATCH /orgs/:org/pre-receive-hooks/:id - -<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> - -### Response - -<%= headers 200 %><%= json :pre_receive_hook_org_update %> - -## Remove enforcment overrides for a pre-receive hook - -Removes any overrides for this hook at the org level for this org. - - DELETE /orgs/:org/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md deleted file mode 100644 index 2eef1d9459..0000000000 --- a/content/v3/repos/pre_receive_hooks.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Repository Pre-receive Hooks ---- - -# Repository Pre-receive Hooks (Enterprise) - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - - -{:toc} - -The Repository Pre-receive Hooks API allows you to view and modify -enforcement of the pre-receive hooks that are available to a repository. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -| Name | Type | Description | -|---------------------|----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this repository, it's organization -owner or global configuration. Authorization to access the endpoint at -`configuration_url` is determined at the owner or site admin level. - -## List pre-receive hooks - -List all pre-receive hooks that are enabled or testing for this -repository as well as any disabled hooks that are allowed to be enabled -at the repository level. Pre-receive hooks that are disabled at a higher -level and are not configurable will not be listed. - - GET /repos/:owner/:repo/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks_repo %> - -## Get a single pre-receive hook - - GET /repos/:owner/:repo/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_repo %> - -## Update pre-receive hook enforcement - -For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` - - PATCH /repos/:owner/:repo/pre-receive-hooks/:id - -<%= json :enforcement => "enabled" %> - -### Response - -<%= headers 200 %><%= json :pre_receive_hook_repo_update %> - -## Remove enforcement overrides for a pre-receive hook - -Deletes any overridden enforcement on this repository for the specified -hook. - - DELETE /repos/:owner/:repo/pre-receive-hooks/:id - -### Response - -Responds with effective values inherited from owner and/or global level. - -<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index b36458f202..fe51837c49 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,9 +80,6 @@

    Members
  • Teams
  • Webhooks
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Hooks (Enterprise)
    • - <% end %>
  • @@ -119,9 +116,6 @@

    Statistics

  • Statuses
  • Webhooks
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Hooks (Enterprise)
    • - <% end %>
  • @@ -153,10 +147,6 @@

    LDAP

  • License
  • Management Console
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Environments
    • -
  • Pre-receive Hooks
    • - <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb deleted file mode 100644 index 6ccf0a4ab9..0000000000 --- a/lib/responses/pre_receive.rb +++ /dev/null @@ -1,136 +0,0 @@ -module GitHub - module Resources - module Responses - URL_OPTIONS = { - :base_api_url => "https://github.example.com/api/v3", - :base_url => "https://github.example.com" - } - - def self.options_to_output(options, keys_to_use) - keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } - end - - def self.pre_receive_environment_download(options = {}) - options = URL_OPTIONS.merge( - :id => 3, - :downloaded_at => '2016-05-26T07:42:53-05:00', - :state => 'success', - :message => nil - ).merge options - options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" - options_to_output options, %w(url state downloaded_at message) - end - - def self.pre_receive_environment(options = {}) - options = URL_OPTIONS.merge( - :id => 1, - :name => 'Default', - :image_url => 'githubenterprise://internal', - :created_at => '2016-05-20T11:35:45-05:00', - :hooks_count => 1, - :download_options => {}, - :default_environment => true - ).merge options - options.update( - :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", - :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", - :download => pre_receive_environment_download(options.merge options[:download_options]) - ) - options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) - end - - def self.pre_receive_script_repository(options = {}) - options = URL_OPTIONS.merge( - :id => 595, - :full_name => "ExampleOrg/hooks", - ).merge options - options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" - options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" - options_to_output options, %w(id full_name url html_url) - end - - def self.pre_receive_hook(options = {}) - options = URL_OPTIONS.merge( - :id => 1, - :name => 'Check Commits', - :script => 'scripts/commmit_check.sh', - :script_repository => { - :id => 595, - :full_name => "DevIT/hooks" - }, - :environment => PRE_RECEIVE_ENVIRONMENT, - :enforcement => "disabled", - :allow_downstream_configuration => false - ).merge options - options[:script_repository][:url] ||= - "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" - options[:script_repository][:html_url] ||= - "#{options[:base_url]}/#{options[:script_repository][:full_name]}" - options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) - end - - def self.pre_receive_hook_repo(options = {}) - options = URL_OPTIONS.merge( - :id => 42, - :name => "Check Commits", - :enforcement => "disabled", - :configuration_url => "/orgs/octocat/pre-receive-hooks/42" - ).merge options - options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" - options_to_output(options, %w(id name enforcement configuration_url)) - end - - def self.pre_receive_hook_org(options = {}) - options = URL_OPTIONS.merge( - :id => 42, - :name => "Check Commits", - :enforcement => "disabled", - :configuration_url => "/admin/pre-receive-hooks/42", - :allow_downstream_configuration => true - ).merge options - options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" - options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) - end - - PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ - :id => 2, - :name => "DevTools Hook Env", - :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", - :default_environment => false - }) - - PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ - "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) - }) - - PRE_RECEIVE_ENVIRONMENTS ||= [ - pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), - PRE_RECEIVE_ENVIRONMENT - ] - - PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= - pre_receive_environment_download :state => 'not_started', - :downloaded_at => nil - - PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download - - PRE_RECEIVE_HOOK ||= pre_receive_hook - PRE_RECEIVE_HOOKS ||= [pre_receive_hook] - PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment - - PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo - - PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] - - PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", - :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" - - PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org - PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] - PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", - :configuration_url => "/orgs/octocat/pre-receive-hooks/42", - :allow_downstream_configuration => false - - end - end -end From c0f824227f093ff2436bd41f074e638a22614854 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 2 Aug 2016 13:17:09 -0700 Subject: [PATCH 12/29] Sync changes from upstream repository --- .gitignore | 2 ++ Rakefile | 7 +++++++ script/enterprise-backport | 2 +- tasks/utils.rake | 2 +- tasks/versioning.rake | 4 ++++ 5 files changed, 15 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 482b02b2a9..cb3b5339eb 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ !/assets/vendor/lunr.js/lunr.js !/assets/vendor/lunr.js/lunr.min.js +_site/ +enterprise/ output tmp .DS_Store diff --git a/Rakefile b/Rakefile index 066f1ab736..b733333cb9 100644 --- a/Rakefile +++ b/Rakefile @@ -20,6 +20,10 @@ task :build do end end +task :build_latest_ent do + puts sh "script/enterprise-backport #{config[:versions].first} --keep" +end + desc "Test the output" task :test => [:remove_tmp_dir, :remove_output_dir, :build] do Rake::Task['spec'].invoke @@ -80,6 +84,9 @@ end namespace :assets do task :precompile => [:build] do sh 'mv output _site/' + Rake::Task['build_latest_ent'].invoke + sh "mkdir -p _site/enterprise/#{config[:versions].first}" + sh "mv output/* _site/enterprise/#{config[:versions].first}" end end diff --git a/script/enterprise-backport b/script/enterprise-backport index 8e8857ce87..8fa7c93ac1 100755 --- a/script/enterprise-backport +++ b/script/enterprise-backport @@ -52,7 +52,7 @@ data_variables: Nanoc::Int::SiteLoader.new.new_with_config(versioned_config).compile puts `node_modules/gulp/bin/gulp.js assets` - fail unless $CHILD_STATUS.to_i == 0 + raise unless $CHILD_STATUS.to_i == 0 versioned_config end diff --git a/tasks/utils.rake b/tasks/utils.rake index de2bc3aa0b..715373183d 100644 --- a/tasks/utils.rake +++ b/tasks/utils.rake @@ -1,3 +1,4 @@ +require 'yaml' require 'json' require 'active_support/core_ext/hash' @@ -8,4 +9,3 @@ end def symbolize_hash(hash) hash.deep_symbolize_keys end - diff --git a/tasks/versioning.rake b/tasks/versioning.rake index ad161de5d7..20baf25473 100644 --- a/tasks/versioning.rake +++ b/tasks/versioning.rake @@ -131,3 +131,7 @@ def cleanup FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/vendor" FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/images" end + +def keep? + ARGV.include?('--keep') +end From c07350e4198e0da96e143e24bd13bfcdefd6a212 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 10:13:50 -0700 Subject: [PATCH 13/29] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ++++++++++++++++++ content/v3/enterprise/pre_receive_hooks.md | 110 ++++++++++ content/v3/orgs/pre_receive_hooks.md | 83 ++++++++ content/v3/repos/pre_receive_hooks.md | 88 ++++++++ layouts/sidebar.html | 10 + lib/responses/pre_receive.rb | 136 ++++++++++++ nanoc.yaml | 3 +- 7 files changed, 622 insertions(+), 1 deletion(-) create mode 100644 content/v3/enterprise/pre_receive_environments.md create mode 100644 content/v3/enterprise/pre_receive_hooks.md create mode 100644 content/v3/orgs/pre_receive_hooks.md create mode 100644 content/v3/repos/pre_receive_hooks.md create mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md new file mode 100644 index 0000000000..ac12fe2409 --- /dev/null +++ b/content/v3/enterprise/pre_receive_environments.md @@ -0,0 +1,193 @@ +--- +title: Pre-receive Environments +--- + +# Pre-receive Environments + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. *It is only available to [authenticated](/v3/#authentication) site administrators.* Normal users will receive a `404` response if they try to access it. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Environment + +| Name | Type | Description | +|-----------------------|-----------|----------------------------------------------------------------------------| +| `name` | `string` | The name of the environment as displayed in the UI. | +| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | +| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | +| `download` | `object` | This environment's download status. | +| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | + +### Pre-receive Environment Download + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + + +## Get a single pre-receive environment + + GET /admin/pre-receive-environments/:id + +<%= headers 200 %> +<%= json :pre_receive_environment %> + +## List pre-receive environments + + GET /admin/pre_receive_environments + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_environments %> + +## Create a pre-receive environment + + POST /admin/pre_receive_environments + +### Parameters + +| Name | Type | Description | +|-------------|----------|-------------------------------------------------------------------------| +| `name` | `string` | **Required**. The new pre-receive environment's name. | +| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | + +<%= json \ + :name => 'DevTools Hook Env', + :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' +%> + +### Response + +<%= headers 201 %> +<%= json :pre_receive_environment_create %> + +## Edit a pre-receive environment + + PATCH /admin/pre_receive_environments/:id + +### Parameters + +| Name | Type | Description | +|-------------|----------|-----------------------------------------------------------| +| `name` | `string` | This pre-receive environment's new name. | +| `image_url` | `string` | URL from which to download a tarball of this environment. | + +### Response +<%= headers 200 %> +<%= json :pre_receive_environment %> + +#### Client Errors + +If you attempt to modify the default environment, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +## Delete a pre-receive environment + + DELETE /admin/pre_receive_environments/:id + +### Response + +<%= headers 204 %> + +#### Client Errors + +If you attempt to delete an environment that cannot be deleted, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Cannot delete environment that has hooks_ +- _Cannot delete environment when download is in progress_ + +## Get a pre-receive environment's download status + +In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. + + GET /admin/pre-receive-environments/:id/downloads/latest + +<%= headers 200 %> +<%= json :pre_receive_environment_download_2 %> + +### Object attributes + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + +## Trigger a pre-receive environment download + +Triggers a new download of the environment tarball from the environment's `image_url`. When the download is finished, the newly downloaded tarball will overwrite the existing environment. + + POST /admin/pre_receive_environments/:id/downloads + +### Response + +<%= headers 202 %> +<%= json :pre_receive_environment_download %> + +#### Client Errors + +If a download cannot be triggered, you will get a reponse like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Can not start a new download when a download is in progress' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Can not start a new download when a download is in progress_ + diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md new file mode 100644 index 0000000000..876f242bbd --- /dev/null +++ b/content/v3/enterprise/pre_receive_hooks.md @@ -0,0 +1,110 @@ +--- +title: Pre-receive Hooks +--- + +# Pre-receive Hooks + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Hooks API allows you to create, list, update and delete +pre-receive hooks. *It is only available to +[authenticated](/v3/#authentication) site administrators.* Normal users +will receive a `404` response if they try to access it. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Hook + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `script` | `string` | The script that the hook runs. | +| `script_repository` | `object` | The GitHub repository where the script is kept. | +| `environment` | `object` | The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +## Get a single pre-receive hook + + GET /admin/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook %> + +## List pre-receive hooks + + GET /admin/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks %> + +## Create a pre-receive hook + + POST /admin/pre-receive-hooks + +### Parameters + +| Name | Type | Description | +|----------------------------------|-----------|----------------------------------------------------------------------------------| +| `name` | `string` | **Required** The name of the hook. | +| `script` | `string` | **Required** The script that the hook runs. | +| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | +| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | + +<%= json \ + :name => "Check Commits", + :script => "scripts/commit_check.sh", + :enforcement => "disabled", + :allow_downstream_configuration => false, + :script_repository => { :full_name => "DevIT/hooks" }, + :environment => { :id => 2 } +%> + +### Response +<%= headers 201 %> +<%= json :pre_receive_hook %> + +## Edit a pre-receive hook + + PATCH /admin/pre_receive_hooks/:id + +<%= json \ + :name => "Check Commits", + :environment => { :id => 1 }, + :allow_downstream_configuration => true +%> + +### Response +<%= headers 200 %> +<%= json :pre_receive_hook_update %> + +## Delete a pre-receive hook + + DELETE /admin/pre_receive_hooks/:id + +### Response + +<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md new file mode 100644 index 0000000000..7d3afc0bd4 --- /dev/null +++ b/content/v3/orgs/pre_receive_hooks.md @@ -0,0 +1,83 @@ +--- +title: Organization Pre-receive Hooks +--- + +# Organization Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Organization Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to an organization. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this endpoint or this hook's global +configuration. Only site admins are able to access the global configuration. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +organization as well as any disabled hooks that can be configured at the +organization level. Globally disabled pre-receive hooks that do not allow +downstream configuration are not listed. + + GET /orgs/:org/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_org %> + +## Get a single pre-receive hook + + GET /orgs/:org:pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the org level, you can set +`enforcement` and `allow_downstream_configuration` + + PATCH /orgs/:org/pre-receive-hooks/:id + +<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_org_update %> + +## Remove enforcment overrides for a pre-receive hook + +Removes any overrides for this hook at the org level for this org. + + DELETE /orgs/:org/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md new file mode 100644 index 0000000000..2eef1d9459 --- /dev/null +++ b/content/v3/repos/pre_receive_hooks.md @@ -0,0 +1,88 @@ +--- +title: Repository Pre-receive Hooks +--- + +# Repository Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + + +{:toc} + +The Repository Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to a repository. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|---------------------|----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this repository, it's organization +owner or global configuration. Authorization to access the endpoint at +`configuration_url` is determined at the owner or site admin level. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +repository as well as any disabled hooks that are allowed to be enabled +at the repository level. Pre-receive hooks that are disabled at a higher +level and are not configurable will not be listed. + + GET /repos/:owner/:repo/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_repo %> + +## Get a single pre-receive hook + + GET /repos/:owner/:repo/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` + + PATCH /repos/:owner/:repo/pre-receive-hooks/:id + +<%= json :enforcement => "enabled" %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_repo_update %> + +## Remove enforcement overrides for a pre-receive hook + +Deletes any overridden enforcement on this repository for the specified +hook. + + DELETE /repos/:owner/:repo/pre-receive-hooks/:id + +### Response + +Responds with effective values inherited from owner and/or global level. + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index fe51837c49..35dd666473 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,6 +80,9 @@

    Members
  • Teams
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -116,6 +119,9 @@

    Statistics

  • Statuses
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -147,6 +153,10 @@

    LDAP

  • License
  • Management Console
    • + <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.7) %> +
  • Pre-receive Environments
    • +
  • Pre-receive Hooks
    • + <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb new file mode 100644 index 0000000000..6ccf0a4ab9 --- /dev/null +++ b/lib/responses/pre_receive.rb @@ -0,0 +1,136 @@ +module GitHub + module Resources + module Responses + URL_OPTIONS = { + :base_api_url => "https://github.example.com/api/v3", + :base_url => "https://github.example.com" + } + + def self.options_to_output(options, keys_to_use) + keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } + end + + def self.pre_receive_environment_download(options = {}) + options = URL_OPTIONS.merge( + :id => 3, + :downloaded_at => '2016-05-26T07:42:53-05:00', + :state => 'success', + :message => nil + ).merge options + options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" + options_to_output options, %w(url state downloaded_at message) + end + + def self.pre_receive_environment(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Default', + :image_url => 'githubenterprise://internal', + :created_at => '2016-05-20T11:35:45-05:00', + :hooks_count => 1, + :download_options => {}, + :default_environment => true + ).merge options + options.update( + :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", + :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", + :download => pre_receive_environment_download(options.merge options[:download_options]) + ) + options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) + end + + def self.pre_receive_script_repository(options = {}) + options = URL_OPTIONS.merge( + :id => 595, + :full_name => "ExampleOrg/hooks", + ).merge options + options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" + options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output options, %w(id full_name url html_url) + end + + def self.pre_receive_hook(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Check Commits', + :script => 'scripts/commmit_check.sh', + :script_repository => { + :id => 595, + :full_name => "DevIT/hooks" + }, + :environment => PRE_RECEIVE_ENVIRONMENT, + :enforcement => "disabled", + :allow_downstream_configuration => false + ).merge options + options[:script_repository][:url] ||= + "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" + options[:script_repository][:html_url] ||= + "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) + end + + def self.pre_receive_hook_repo(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42" + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url)) + end + + def self.pre_receive_hook_org(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/admin/pre-receive-hooks/42", + :allow_downstream_configuration => true + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) + end + + PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ + :id => 2, + :name => "DevTools Hook Env", + :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", + :default_environment => false + }) + + PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ + "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) + }) + + PRE_RECEIVE_ENVIRONMENTS ||= [ + pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), + PRE_RECEIVE_ENVIRONMENT + ] + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= + pre_receive_environment_download :state => 'not_started', + :downloaded_at => nil + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download + + PRE_RECEIVE_HOOK ||= pre_receive_hook + PRE_RECEIVE_HOOKS ||= [pre_receive_hook] + PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment + + PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo + + PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] + + PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", + :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" + + PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org + PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] + PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42", + :allow_downstream_configuration => false + + end + end +end diff --git a/nanoc.yaml b/nanoc.yaml index 5dc691517e..1f22d618df 100644 --- a/nanoc.yaml +++ b/nanoc.yaml @@ -12,7 +12,8 @@ pipeline_config: asset_root: https://a248.e.akamai.net/assets.github.com/images/icons versions: - - &latest_enterprise_version 2.6 + - &latest_enterprise_version 2.7 + - 2.6 - 2.5 - 2.4 - 2.3 From 26e8ca5c900f4e244ef7514e0f1f365822060628 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 10:59:40 -0700 Subject: [PATCH 14/29] Sync changes from upstream repository --- repository-sync | 1 + 1 file changed, 1 insertion(+) create mode 100644 repository-sync diff --git a/repository-sync b/repository-sync new file mode 100644 index 0000000000..d00491fd7e --- /dev/null +++ b/repository-sync @@ -0,0 +1 @@ +1 From 30ec6f73d02dfcfe55a7fdc41f0d1c4225be5323 Mon Sep 17 00:00:00 2001 From: Dirkjan Bussink Date: Wed, 3 Aug 2016 20:02:50 +0200 Subject: [PATCH 15/29] Revert "Sync changes from upstream repository" This reverts commit c0f824227f093ff2436bd41f074e638a22614854. --- .gitignore | 2 -- Rakefile | 7 ------- script/enterprise-backport | 2 +- tasks/utils.rake | 2 +- tasks/versioning.rake | 4 ---- 5 files changed, 2 insertions(+), 15 deletions(-) diff --git a/.gitignore b/.gitignore index cb3b5339eb..482b02b2a9 100644 --- a/.gitignore +++ b/.gitignore @@ -12,8 +12,6 @@ !/assets/vendor/lunr.js/lunr.js !/assets/vendor/lunr.js/lunr.min.js -_site/ -enterprise/ output tmp .DS_Store diff --git a/Rakefile b/Rakefile index b733333cb9..066f1ab736 100644 --- a/Rakefile +++ b/Rakefile @@ -20,10 +20,6 @@ task :build do end end -task :build_latest_ent do - puts sh "script/enterprise-backport #{config[:versions].first} --keep" -end - desc "Test the output" task :test => [:remove_tmp_dir, :remove_output_dir, :build] do Rake::Task['spec'].invoke @@ -84,9 +80,6 @@ end namespace :assets do task :precompile => [:build] do sh 'mv output _site/' - Rake::Task['build_latest_ent'].invoke - sh "mkdir -p _site/enterprise/#{config[:versions].first}" - sh "mv output/* _site/enterprise/#{config[:versions].first}" end end diff --git a/script/enterprise-backport b/script/enterprise-backport index 8fa7c93ac1..8e8857ce87 100755 --- a/script/enterprise-backport +++ b/script/enterprise-backport @@ -52,7 +52,7 @@ data_variables: Nanoc::Int::SiteLoader.new.new_with_config(versioned_config).compile puts `node_modules/gulp/bin/gulp.js assets` - raise unless $CHILD_STATUS.to_i == 0 + fail unless $CHILD_STATUS.to_i == 0 versioned_config end diff --git a/tasks/utils.rake b/tasks/utils.rake index 715373183d..de2bc3aa0b 100644 --- a/tasks/utils.rake +++ b/tasks/utils.rake @@ -1,4 +1,3 @@ -require 'yaml' require 'json' require 'active_support/core_ext/hash' @@ -9,3 +8,4 @@ end def symbolize_hash(hash) hash.deep_symbolize_keys end + diff --git a/tasks/versioning.rake b/tasks/versioning.rake index 20baf25473..ad161de5d7 100644 --- a/tasks/versioning.rake +++ b/tasks/versioning.rake @@ -131,7 +131,3 @@ def cleanup FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/vendor" FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/images" end - -def keep? - ARGV.include?('--keep') -end From daa9070241b47862deaf7109da5d7c1e3808d792 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 11:37:23 -0700 Subject: [PATCH 16/29] Sync changes from upstream repository --- content/v3/reactions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/reactions.md b/content/v3/reactions.md index a492093f4c..d8effc8a38 100644 --- a/content/v3/reactions.md +++ b/content/v3/reactions.md @@ -2,7 +2,7 @@ title: Reactions --- -{% if page.version == 'dotcom' %} +{% if page.version == 'dotcom' or page.version >= 2.7 %} # Reactions @@ -24,7 +24,7 @@ title: Reactions ## Reaction types - + When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): content | emoji From 685b58c584cd2bfe48de0add28924ee6adacdd22 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 4 Aug 2016 09:47:49 -0700 Subject: [PATCH 17/29] Sync changes from upstream repository --- content/v3/repos/collaborators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index 5bd3ad05b4..5e22e210d7 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -19,11 +19,11 @@ collaborators list. ### Response +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} + <%= headers 200, :pagination => default_pagination_rels %> <%= json(:user) { |h| [h] } %> -{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} - ### Alternative response with extra repository information {{#tip}} From 3643cbc394ce96be53382d27e7c134b814758b82 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 5 Aug 2016 09:44:59 -0700 Subject: [PATCH 18/29] Sync changes from upstream repository --- content/integrations-directory/getting-listed.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/content/integrations-directory/getting-listed.md b/content/integrations-directory/getting-listed.md index 907a9088c0..7a96f11057 100644 --- a/content/integrations-directory/getting-listed.md +++ b/content/integrations-directory/getting-listed.md @@ -37,11 +37,7 @@ marketing site. As your product changes, keep your Integration Directory listing ### Provide categories for your listing -Help GitHub users find your integration faster with the appropriate categories. Please send us your suggested categories for the listing. We reserve the right to remove categories from a listing, but we won't add any categories without your approval. Currently, the following categories are available: - -* Code -* Collaborate -* Ship +Help GitHub users find your integration faster with the appropriate categories. Please send us your suggested categories for the listing from those available in the [Integrations Directory](https://github.com/integrations). If you don't see a category that fits quite right, just let us know. We reserve the right to change categories associated with the listing. If we do so, we'll do our best to keep you informed. If your integration supports both GitHub.com and GitHub Enterprise, please let us know. From 420621464ee2a0b96a9c3b089cd085421e3ccab3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 8 Aug 2016 03:11:46 -0700 Subject: [PATCH 19/29] Sync changes from upstream repository --- ...pages-preiew-api.md => 2016-07-06-github-pages-preview-api.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/changes/{2016-07-06-github-pages-preiew-api.md => 2016-07-06-github-pages-preview-api.md} (100%) diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preview-api.md similarity index 100% rename from content/changes/2016-07-06-github-pages-preiew-api.md rename to content/changes/2016-07-06-github-pages-preview-api.md From 6d983225b476e7cbaf5152001bc89fc5261363a3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 9 Aug 2016 11:45:20 -0700 Subject: [PATCH 20/29] Sync changes from upstream repository --- ...om-organization-api-responses-for-owner.md | 22 +++++++++++++++++++ content/v3/orgs.md | 6 +++++ 2 files changed, 28 insertions(+) create mode 100644 content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md diff --git a/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md b/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md new file mode 100644 index 0000000000..22f0e9cd3c --- /dev/null +++ b/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md @@ -0,0 +1,22 @@ +--- +title: "Breaking change: Removed sensitive fields from Organization API responses for non-owners" +author_name: kdaigle +--- + +We're removing some values from [Organization API](https://developer.github.com/v3/orgs/) responses to help protect our +users' privacy. Previously, these fields were returned to all members of the organization. +As of today, you must be an Organization owner to +receive values for the following fields in Organization responses: + +* `private_gists` +* `disk_usage` +* `collaborators` +* `billing_email` + +If you're not an organization owner, the above keys will now return `null`. +We will continue to send these fields without their values to minimize the impact +of this change. + +If you have any questions or feedback, please [drop us a line][contact]. + +[contact]: https://github.com/contact?form[subject]=Removed+sensitive+fields+from+org+api diff --git a/content/v3/orgs.md b/content/v3/orgs.md index 3ba152583b..aa7419a031 100644 --- a/content/v3/orgs.md +++ b/content/v3/orgs.md @@ -61,6 +61,12 @@ This method only lists *public* memberships, regardless of authentication. If yo ## Get an organization +{% if page.version == 'dotcom' or page.version >= 2.8 %} +Note: To receive values for `private_gists`, `disk_usage`, `collaborators`, and +`billing_email` in the Organization response, the authenticated user must be an +organization owner and have authorized the `admin:org` scope. +{% endif %} + GET /orgs/:org ### Response From 084e21e2c4a5ed8cbc88f34f5b4f26b16dd4d5ea Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 15 Aug 2016 00:43:54 -0700 Subject: [PATCH 21/29] Sync changes from upstream repository --- content/v3/repos/branches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/repos/branches.md b/content/v3/repos/branches.md index 1c11628394..e620efd95c 100644 --- a/content/v3/repos/branches.md +++ b/content/v3/repos/branches.md @@ -228,7 +228,7 @@ Protecting a branch requires admin access. ### Parameters -You can pass two objects: `required_status_checks` and `restrictions`. Both can have the value `null` for disabled. +You must pass two objects: `required_status_checks` and `restrictions`. Both can have the value `null` for disabled. The `required_status_checks` object must have the following keys: From e0389e571a7f18fdccdebdd06dc67245c8357a5e Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 15 Aug 2016 06:46:21 -0700 Subject: [PATCH 22/29] Sync changes from upstream repository --- .../changes/2016-08-15-traffic-api-preview.md | 18 ++++ content/v3/repos/traffic.md | 79 ++++++++++++++++ layouts/sidebar.html | 3 + lib/responses/traffic.rb | 94 +++++++++++++++++++ 4 files changed, 194 insertions(+) create mode 100644 content/changes/2016-08-15-traffic-api-preview.md create mode 100644 content/v3/repos/traffic.md create mode 100644 lib/responses/traffic.rb diff --git a/content/changes/2016-08-15-traffic-api-preview.md b/content/changes/2016-08-15-traffic-api-preview.md new file mode 100644 index 0000000000..60b089e380 --- /dev/null +++ b/content/changes/2016-08-15-traffic-api-preview.md @@ -0,0 +1,18 @@ +--- +title: Preview the Repository Traffic API +author_name: shreyasjoshis +--- + + We've added an API for repository traffic, which will let you fetch details about traffic for repositories you have push access to. This data is already available in graphical form in the [Graphs section](https://help.github.com/articles/about-repository-graphs/#traffic) on GitHub.com. + +To access [the Traffic API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.spiderman-preview + +During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice. + +If you have any questions or feedback, please [let us know][contact]! + +[media-type]: /v3/media +[docs]: /v3/repos/traffic/ +[contact]: https://github.com/contact?form%5Bsubject%5D=Traffic+API diff --git a/content/v3/repos/traffic.md b/content/v3/repos/traffic.md new file mode 100644 index 0000000000..483197db77 --- /dev/null +++ b/content/v3/repos/traffic.md @@ -0,0 +1,79 @@ +--- +title: Traffic +--- + +# Traffic +{{#tip}} + + + + APIs for repository traffic are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-08-15-traffic-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.spiderman-preview + +{{/tip}} + +{:toc} + +For repositories that you have push access to, the traffic API provides access +to the information provided in the [graphs section](https://help.github.com/articles/about-repository-graphs/#traffic). + + + +## List referrers + +Get the top 10 referrers over the last 14 days. + + GET /repos/:owner/:repo/traffic/popular/referrers + +### Response + +<%= headers 200 %> +<%= json(:traffic_referrers) %> + +## List paths + +Get the top 10 popular contents over the last 14 days. + + GET /repos/:owner/:repo/traffic/popular/paths + +### Response + +<%= headers 200%> +<%= json(:traffic_contents) %> + +## Views + +Get the total number of views and breakdown per day or week for the last 14 days. + + GET /repos/:owner/:repo/traffic/views + +### Parameters +Name | Type | Description +-----|------|-------------- +`per`|string|Must be one of: `day`, `week`. Default: `day` + + +### Response +<%= headers 200 %> +<%= json(:traffic_views) %> + +## Clones + +Get the total number of clones and breakdown per day or week for the last 14 days. + + GET /repos/:owner/:repo/traffic/clones + +### Parameters +Name | Type | Description +-----|------|-------------- +`per`|string|Must be one of: `day`, `week`. Default: `day` + +### Response + +<%= headers 200 %> +<%= json(:traffic_clones) %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 35dd666473..46f010e310 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -118,6 +118,9 @@

    Releases
  • Statistics
  • Statuses
    • + <% if @item[:version] == 'dotcom' %> +
  • Traffic
    • + <% end %>
  • Webhooks
    • <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %>
  • Pre-receive Hooks (Enterprise)
    • diff --git a/lib/responses/traffic.rb b/lib/responses/traffic.rb new file mode 100644 index 0000000000..ff8e8cb0ba --- /dev/null +++ b/lib/responses/traffic.rb @@ -0,0 +1,94 @@ +module GitHub + module Resources + module Responses + + TRAFFIC_REFERRERS ||= [ + {"referrer" => "Google", "count" => 4, "uniques" => 3}, + {"referrer" => "stackoverflow.com", "count" => 2, "uniques" => 2}, + {"referrer" => "eggsonbread.com", "count" => 1, "uniques" => 1}, + {"referrer" => "yandex.ru", "count" => 1, "uniques" => 1}] + + TRAFFIC_CONTENTS ||= [ + { + "path" => "/github/hubot", + "title" => "github/hubot: A customizable life embetterment robot.", + "count" => 3542, + "uniques" => 2225 + }, + { + "path" => "/github/hubot/blob/master/docs/scripting.md", + "title" => "hubot/scripting.md at master · github/hubot · GitHub", + "count" => 1707, + "uniques" => 804 + }, + { + "path" => "/github/hubot/tree/master/docs", + "title" => "hubot/docs at master · github/hubot · GitHub", + "count" => 685, + "uniques" => 435 + }, + { + "path" => "/github/hubot/tree/master/src", + "title" => "hubot/src at master · github/hubot · GitHub", + "count" => 577, + "uniques" => 347 + }, + { + "path" => "/github/hubot/blob/master/docs/index.md", + "title" => "hubot/index.md at master · github/hubot · GitHub", + "count" => 379, + "uniques" => 259 + }, + { + "path" => "/github/hubot/blob/master/docs/adapters.md", + "title" => "hubot/adapters.md at master · github/hubot · GitHub", + "count" => 354, + "uniques" => 201 + }, + { + "path" => "/github/hubot/tree/master/examples", + "title" => "hubot/examples at master · github/hubot · GitHub", + "count" => 340, + "uniques" => 260 + }, + { + "path" => "/github/hubot/blob/master/docs/deploying/heroku.md", + "title" => "hubot/heroku.md at master · github/hubot · GitHub", + "count" => 324, + "uniques" => 217 + }, + { + "path" => "/github/hubot/blob/master/src/robot.coffee", + "title" => "hubot/robot.coffee at master · github/hubot · GitHub", + "count" => 293, + "uniques" => 191 + }, + { + "path" => "/github/hubot/blob/master/LICENSE.md", + "title" => "hubot/LICENSE.md at master · github/hubot · GitHub", + "count" => 281, + "uniques" => 222 + }] + + TRAFFIC_VIEWS ||= { + "count" => 7, + "uniques" => 6, + "views" => [ + {"timestamp" => 1464710400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1464732000000, "count" => 2, "uniques" => 1}, + {"timestamp" => 1465214400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465218000000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465300800000, "count" => 2, "uniques" => 2}]} + + TRAFFIC_CLONES ||= { + "count" => 7, + "uniques" => 6, + "clones" => [ + {"timestamp" => 1464710400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1464732000000, "count" => 2, "uniques" => 1}, + {"timestamp" => 1465214400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465218000000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465300800000, "count" => 2, "uniques" => 2}]} + end + end +end From 3f411bda1309466a7fd1da5092801e52b0ef103f Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 16 Aug 2016 04:50:19 -0700 Subject: [PATCH 23/29] Sync changes from upstream repository --- content/v3/users.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/users.md b/content/v3/users.md index d8caa605d1..11e5479a4c 100644 --- a/content/v3/users.md +++ b/content/v3/users.md @@ -68,7 +68,7 @@ Name | Type | Description ## Get all users -Lists all users, in the order that they signed up on {{ site.data.variables.product.product_name }}. +Lists all users, in the order that they signed up on {{ site.data.variables.product.product_name }}. This list includes personal user accounts and organization accounts. Note: Pagination is powered exclusively by the `since` parameter. Use the [Link header](/v3/#link-header) to get the URL for the next page of From 9190dd5a0719f666bdcfe52e808d0ce0624cdedb Mon Sep 17 00:00:00 2001 From: Jeff Schering Date: Wed, 17 Aug 2016 10:42:15 -0700 Subject: [PATCH 24/29] Update basics-of-authentication.md Deleted an extra in the views/index.erb sample, line 68 --- content/guides/basics-of-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/basics-of-authentication.md b/content/guides/basics-of-authentication.md index 180f1a3ccd..f67f9e8f0e 100644 --- a/content/guides/basics-of-authentication.md +++ b/content/guides/basics-of-authentication.md @@ -65,7 +65,7 @@ Next, in _views/index.erb_, paste this content:

    We're going to now talk to the GitHub API. Ready? - Click here to begin! + Click here to begin!

    If that link doesn't work, remember to provide your own Client ID! From cb063a6aa0b6918b230934c6017160eb4c01cf2f Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 23 Aug 2016 14:51:30 -0700 Subject: [PATCH 25/29] Sync changes from upstream repository --- content/changes/2016-08-23-change-base.md | 25 +++++++++++++++++++++++ content/v3/pulls.md | 10 ++++++--- 2 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 content/changes/2016-08-23-change-base.md diff --git a/content/changes/2016-08-23-change-base.md b/content/changes/2016-08-23-change-base.md new file mode 100644 index 0000000000..a83f67b8e3 --- /dev/null +++ b/content/changes/2016-08-23-change-base.md @@ -0,0 +1,25 @@ +--- +title: API changes for changing the base branch on Pull Requests +author_name: scottjg +--- +GitHub recently added the ability to [change the base branch][blog post] on a Pull Request after it's created. Now we're updating the Pull Request API to enable the new functionality. + +For example: + +``` command-line +curl "https://api.github.com/repos/github/hubot/pulls/123" \ + -H 'Authorization: token TOKEN' \ + -d '{ "base": "master" }' +``` + +The Pull Request base will be updated to point to the master branch. + +You can learn more about the new responses and endpoints in the updated [Pull Request][pulls] documentation. + +If you have any questions or feedback, please [let us know][contact]! + + +[pulls]: /v3/pulls +[blog post]: https://github.com/blog/2224-change-the-base-branch-of-a-pull-request +[contact]: https://github.com/contact?form%5Bsubject%5D=Change+base+on+Pull+Requests + diff --git a/content/v3/pulls.md b/content/v3/pulls.md index 7d73679708..332c98ff3d 100644 --- a/content/v3/pulls.md +++ b/content/v3/pulls.md @@ -87,7 +87,7 @@ Name | Type | Description -----|------|------------- `title`|`string` | **Required**. The title of the pull request. `head`|`string` | **Required**. The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace `head` with a user like this: `username:branch`. -`base`|`string` | **Required**. The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository. +`base`|`string` | **Required**. The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository. `body`|`string` | The contents of the pull request. @@ -132,14 +132,18 @@ Name | Type | Description -----|------|-------------- `title`|`string` | The title of the pull request. `body`|`string` | The contents of the pull request. -`state`|`string` | State of this Pull Request. Either `open` or `closed`. +`state`|`string` | State of this Pull Request. Either `open` or `closed`.{% if page.version == 'dotcom' or page.version >= 2.8 %} +`base`|`string` | The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository. +{% endif %} #### Example <%= json \ :title => "new title", :body => "updated body", - :state => "open" + :state => "open"{% if page.version == 'dotcom' or page.version >= 2.8 %}, + :base => "master" +{% endif %} %> ### Response From 0e5a5b8fc39140d9688a2bbb0b999057adfecb1f Mon Sep 17 00:00:00 2001 From: Morton Fox Date: Wed, 31 Aug 2016 00:16:45 -0400 Subject: [PATCH 26/29] Update the pull request help link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a1e3bfcc9..fd73c1d298 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ This is a GitHub API resource built with [Nanoc][nanoc]. -All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](http://help.github.com/send-pull-requests/). +All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](https://help.github.com/articles/creating-a-pull-request/). ## Development From 6e3b1dac0fa8654fdd6503d17f9a6a4337ab69fd Mon Sep 17 00:00:00 2001 From: Garen Torikian Date: Fri, 2 Sep 2016 23:12:03 -0700 Subject: [PATCH 27/29] No longer necessary. --- CNAME | 1 - 1 file changed, 1 deletion(-) delete mode 100644 CNAME diff --git a/CNAME b/CNAME deleted file mode 100644 index 82c2e93c12..0000000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -developer.github.com From 64f712176ee30c47ea7a20231c38d72e61529e40 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 8 Sep 2016 18:26:53 -0500 Subject: [PATCH 28/29] Update README --- README.md | 302 ++++++++++++++++++++++++------------------------------ 1 file changed, 136 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index fd73c1d298..620e7a2091 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,136 @@ -# developer.github.com [![Build Status](https://travis-ci.org/github/developer.github.com.svg?branch=master)](https://travis-ci.org/github/developer.github.com) - - -This is a GitHub API resource built with [Nanoc][nanoc]. - -All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](https://help.github.com/articles/creating-a-pull-request/). - -## Development - -You can fetch the latest dependencies by opening the command line and running `script/bootstrap`: - -``` sh -$ script/bootstrap -==> Installing gem dependencies… -==> Installing npm dependencies… -``` - -You'll need Ruby and Node installed on your system. The required versions for each of these languages can be found in the *.ruby-version* and *package.json* files, respectively. - -You can run `bundle exec rake build` to generate the site, but it's often more useful -to simply build the server *and* start the site at the same time. - -Nanoc compiles the site into static files living in `output`. It's -smart enough not to try to compile unchanged files. - -You can start the site with `script/server`: - -``` sh -$ script/server -Loading site data... -Compiling site... - create [0.28s] output/index.html - create [1.31s] output/v3/gists/comments/index.html - identical [1.92s] output/v3/gists/index.html - identical [0.25s] output/v3/issues/comments/index.html - update [0.99s] output/v3/issues/labels/index.html - update [0.05s] output/v3/index.html - … - -Site compiled in 5.81s. -``` - -The site is hosted at `http://localhost:4000`. - -Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about Nanoc. - -[nanoc]: http://nanoc.ws/ - -### Enterprise - -To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: - -``` sh -$ script/server 2.6 -``` - -Note that live reloading is not available for Enterprise documentation. - -## Styleguide - -Not sure how to structure the docs? Here's what the structure of the -API docs should look like: - - # API title - - {:toc} - - ## API endpoint title - - [VERB] /path/to/endpoint - - ### Parameters - - Name | Type | Description - -----|------|-------------- - `name`|`type` | Description. - - ### Input (request JSON body) - - Name | Type | Description - -----|------|-------------- - `name`|`type` | Description. - - ### Response - - <%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %> - <%= json :resource_name %> - -**Note**: We're using [Kramdown Markdown extensions](http://kramdown.gettalong.org/syntax.html), such as definition lists. - -### JSON Responses - -We specify the JSON responses in Ruby so that we don't have to write -them by hand all over the docs. You can render the JSON for a resource -like this: - -```erb -<%= json :issue %> -``` - -This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`. - -Some actions return arrays. You can modify the JSON by passing a block: - -```erb -<%= json(:issue) { |hash| [hash] } %> -``` - -There is also a rake task for generating JSON files from the sample responses in the documentation: - -``` sh -$ rake generate_json_from_responses -``` - -The generated files will end up in *json-dump/*. - -### Terminal blocks - -You can specify terminal blocks by using the `command-line` syntax highlighting. - - ``` command-line - $ curl foobar - ``` - -You can use certain characters, like `$` and `#`, to emphasize different parts -of commands. - - ``` command-line - # call foobar - $ curl foobar - .... - ``` - -For more information, see [the reference documentation](https://github.com/gjtorikian/extended-markdown-filter#command-line-highlighting). - -## Deploy - -Deployments happen automatically once a PR is merged into `master`. A tool called [Publisher](https://github.com/gjtorikian/publisher) takes the `master` branch, builds it using Nanoc, and publishes the content to `gh-pages`. Thus, any commit to `master` is automatically sent over to `gh-pages`, where it's picked up and served by GitHub Pages. - -## Licenses - -The code to generate the site (everything excluding the assets, content, -and layouts directories) as well as the code samples on the site are -licensed under -[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode). -CC0 waives all copyright restrictions but does not grant you any trademark -permissions. - -Site content (everything in the assets, content, and layouts directories, -excluding files under open source licenses individually marked) is licensed -under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). CC-BY-4.0 -gives you permission to use content for almost any purpose but does not grant -you any trademark permissions, so long as you note the license and give credit, -such as follows: - -> Content based on -> developer.github.com -> used under the -> CC-BY-4.0 -> license. - -This means you can use the code and content in this repository except for -GitHub trademarks in your own projects. - -When you contribute to this repository you are doing so under the above -licenses. +IyBkZXZlbG9wZXIuZ2l0aHViLmNvbQoKKipOT1RFOiBUaGUgZGV2ZWxvcGVy +LmdpdGh1Yi5jb20gd2Vic2l0ZSBpcyBubyBsb25nZXIgb3Blbi1zb3VyY2Uu +KioKCldlIGhhdmUgbW92ZWQgdGhpcyByZXBvc2l0b3J5IGludG8gW291ciBn +aXRodWItYXJjaGl2ZSBvcmdhbml6YXRpb25dKGh0dHBzOi8vZ2l0aHViLmNv +bS9naXRodWItYXJjaGl2ZSkgdG8gc2lnbmlmeSB0aGF0IHdlIGFyZSBubyBs +b25nZXIgYWNjZXB0aW5nIG9wZW4tc291cmNlIGNvbnRyaWJ1dGlvbnMgdG8g +dGhpcyByZXBvc2l0b3J5LiBXZSB3YW50IHRvIHRoYW5rIHRoZSBodW5kcmVk +cyBvZiBjb250cmlidXRvcnMgZm9yIHRoZWlyIGFzc2lzdGFuY2Ugb3ZlciB0 +aGUgeWVhcnMuCgpUaGUgZGVjaXNpb24gdG8gY2xvc2Utc291cmNlIHRoZSBz +aXRlIHN0ZW1zIGZyb20gYSB2YXJpZXR5IG9mIHJlYXNvbnM6CgoxLiBXZSBh +Y3R1YWxseSBhbHJlYWR5IF9oYXZlXyBhIGNsb3NlLXNvdXJjZWQgc2l0ZSwg +d2hpY2ggaXMgd2hlcmUgd2Ugd3JvdGUgZG9jdW1lbnRhdGlvbiBmb3IgdW5y +ZWxlYXNlZCBmZWF0dXJlcy4gV2UgZGVzaWduZWQgYWRkaXRpb25hbCB0b29s +aW5nIHRvIHN1cHBvcnQgdGhpcyB3b3JrZmxvdywgYnV0IHVwZGF0aW5nIHRo +ZSBkb2N1bWVudGF0aW9uIGlzIGEgcHJvY2VzcyB3ZSdkIGxpa2UgdG8gc2lt +cGxpZnkuCjIuIFdlIGJlbGlldmUgdGhhdCBhbnkgb3Blbi1zb3VyY2UgcHJv +amVjdOKAlGJlIGl0IGRvY3VtZW50YXRpb24gb3Igc29mdHdhcmXigJRvdWdo +dCB0byBoYXZlIGRlZGljYXRlZCBtYWludGFpbmVycy4gSXQgYmVjYW1lIGRp +ZmZpY3VsdCB0byBrZWVwIHRoaXMgcmVwb3NpdG9yeSBvcGVuLXNvdXJjZSBi +ZWNhdXNlIGl0IHdhcyBtYWludGFpbmVkIGJ5IHRoZSBiZXN0IGVmZm9ydHMg +b2YgYSBzbWFsbCBncm91cCBvZiBwZW9wbGUuIENsb3NpbmcgdGhlIHNpdGUg +YWxsb3dzIHVzIHRvIGZvY3VzIG9uIHdoYXQncyBpbXBvcnRhbnQsIHdpdGhv +dXQgZmVlbGluZyBndWlsdHkgYXQgbWlzc2luZyByZXZpZXdzIGZyb20gb3Bl +bi1zb3VyY2UgY29udHJpYnV0b3JzLgoKV2UgdGhpbmsgdGhhdCB0aGUgdG9v +bGluZyB3ZSB1c2VkIHRvIGJ1aWxkIHRoaXMgc2l0ZSBpcyBwcmV0dHkgaW50 +ZXJlc3RpbmcsIHNvIHdlJ3JlIG5vdCBnZXR0aW5nIHJpZCBvZiBldmVyeXRo +aW5nLiBXZSBob3BlIHRoYXQgd2hhdCByZW1haW5zIGNhbiBiZSB1c2VkIGFz +IGEgc291cmNlIG9mIGluc3BpcmF0aW9uIGZvciB5b3VyIG93biBzdGF0aWMg +c2l0ZS4KCklmIHlvdSBmaW5kIHNvbWV0aGluZyB0aGF0IG5lZWRzIHRvIGJl +IGZpeGVkLCB5b3UgY2FuIGFsd2F5cyBbY29udGFjdCBvdXIgdGVycmlmaWMg +U3VwcG9ydCB0ZWFtXShodHRwczovL2dpdGh1Yi5jb20vY29udGFjdD9mb3Jt +JTVCc3ViamVjdCU1RD1Nb3ZpbmcrZGV2ZWxvcGVyLmdpdGh1Yi5jb20rdG8r +Z2l0aHViLWFyY2hpdmUpLgoKVGhhbmsgeW91IQoKKiAqICoKClRoaXMgd2Fz +IHRoZSBHaXRIdWIgQVBJIGRvY3VtZW50YXRpb24sIGJ1aWx0IHdpdGggW05h +bm9jXVtuYW5vY10uCgojIyBEZXZlbG9wbWVudAoKWW91IGNhbiBmZXRjaCB0 +aGUgbGF0ZXN0IGRlcGVuZGVuY2llcyBieSBvcGVuaW5nIHRoZSBjb21tYW5k +IGxpbmUgYW5kIHJ1bm5pbmcgYHNjcmlwdC9ib290c3RyYXBgOgoKYGBgIHNo +CiQgc2NyaXB0L2Jvb3RzdHJhcAo9PT4gSW5zdGFsbGluZyBnZW0gZGVwZW5k +ZW5jaWVz4oCmCj09PiBJbnN0YWxsaW5nIG5wbSBkZXBlbmRlbmNpZXPigKYK +YGBgCgpZb3UnbGwgbmVlZCBSdWJ5IGFuZCBOb2RlIGluc3RhbGxlZCBvbiB5 +b3VyIHN5c3RlbS4gVGhlIHJlcXVpcmVkIHZlcnNpb25zIGZvciBlYWNoIG9m +IHRoZXNlIGxhbmd1YWdlcyBjYW4gYmUgZm91bmQgaW4gdGhlICoucnVieS12 +ZXJzaW9uKiBhbmQgKnBhY2thZ2UuanNvbiogZmlsZXMsIHJlc3BlY3RpdmVs +eS4KCllvdSBjYW4gcnVuIGBidW5kbGUgZXhlYyByYWtlIGJ1aWxkYCB0byBn +ZW5lcmF0ZSB0aGUgc2l0ZSwgYnV0IGl0J3Mgb2Z0ZW4gbW9yZSB1c2VmdWwK +dG8gc2ltcGx5IGJ1aWxkIHRoZSBzZXJ2ZXIgKmFuZCogc3RhcnQgdGhlIHNp +dGUgYXQgdGhlIHNhbWUgdGltZS4KCk5hbm9jIGNvbXBpbGVzIHRoZSBzaXRl +IGludG8gc3RhdGljIGZpbGVzIGxpdmluZyBpbiBgb3V0cHV0YC4gIEl0J3MK +c21hcnQgZW5vdWdoIG5vdCB0byB0cnkgdG8gY29tcGlsZSB1bmNoYW5nZWQg +ZmlsZXMuCgpZb3UgY2FuIHN0YXJ0IHRoZSBzaXRlIHdpdGggYHNjcmlwdC9z +ZXJ2ZXJgOgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlcgpMb2FkaW5nIHNpdGUg +ZGF0YS4uLgpDb21waWxpbmcgc2l0ZS4uLgogICBjcmVhdGUgICAgIFswLjI4 +c10gIG91dHB1dC9pbmRleC5odG1sCiAgIGNyZWF0ZSAgICAgWzEuMzFzXSAg +b3V0cHV0L3YzL2dpc3RzL2NvbW1lbnRzL2luZGV4Lmh0bWwKICAgaWRlbnRp +Y2FsICBbMS45MnNdICBvdXRwdXQvdjMvZ2lzdHMvaW5kZXguaHRtbAogICBp +ZGVudGljYWwgIFswLjI1c10gIG91dHB1dC92My9pc3N1ZXMvY29tbWVudHMv +aW5kZXguaHRtbAogICB1cGRhdGUgICAgIFswLjk5c10gIG91dHB1dC92My9p +c3N1ZXMvbGFiZWxzL2luZGV4Lmh0bWwKICAgdXBkYXRlICAgICBbMC4wNXNd +ICBvdXRwdXQvdjMvaW5kZXguaHRtbAogICDigKYKClNpdGUgY29tcGlsZWQg +aW4gNS44MXMuCmBgYAoKVGhlIHNpdGUgaXMgaG9zdGVkIGF0IGBodHRwOi8v +bG9jYWxob3N0OjQwMDBgLgoKTmFub2MgaGFzIFtzb21lIG5pY2UgZG9jdW1l +bnRhdGlvbl0oaHR0cDovL25hbm9jLndzL2RvY3MvdHV0b3JpYWwvKSB0byBn +ZXQgeW91IHN0YXJ0ZWQuICBUaG91Z2ggaWYgeW91J3JlIG1haW5seSBjb25j +ZXJuZWQgd2l0aCBlZGl0aW5nIG9yIGFkZGluZyBjb250ZW50LCB5b3Ugd29u +J3QgbmVlZCB0byBrbm93IG11Y2ggYWJvdXQgTmFub2MuCgpbbmFub2NdOiBo +dHRwOi8vbmFub2Mud3MvCgojIyMgRW50ZXJwcmlzZQoKVG8gZ2VuZXJhdGUg +dGhlIGAvZW50ZXJwcmlzZWAgdmVyc2lvbnMsIHBhc3MgaW4gdGhlIEVudGVy +cHJpc2UgdmVyc2lvbiB0byBgc2NyaXB0L3NlcnZlcmAuIEZvciBleGFtcGxl +OgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlciAyLjYKYGBgCgpOb3RlIHRoYXQg +bGl2ZSByZWxvYWRpbmcgaXMgbm90IGF2YWlsYWJsZSBmb3IgRW50ZXJwcmlz +ZSBkb2N1bWVudGF0aW9uLgoKIyMgU3R5bGVndWlkZQoKTm90IHN1cmUgaG93 +IHRvIHN0cnVjdHVyZSB0aGUgZG9jcz8gIEhlcmUncyB3aGF0IHRoZSBzdHJ1 +Y3R1cmUgb2YgdGhlCkFQSSBkb2NzIHNob3VsZCBsb29rIGxpa2U6CgogICAg +IyBBUEkgdGl0bGUKCiAgICB7OnRvY30KCiAgICAjIyBBUEkgZW5kcG9pbnQg +dGl0bGUKCiAgICAgICAgW1ZFUkJdIC9wYXRoL3RvL2VuZHBvaW50CgogICAg +IyMjIFBhcmFtZXRlcnMKCiAgICBOYW1lIHwgVHlwZSB8IERlc2NyaXB0aW9u +CiAgICAtLS0tLXwtLS0tLS18LS0tLS0tLS0tLS0tLS0KICAgIGBuYW1lYHxg +dHlwZWAgfCBEZXNjcmlwdGlvbi4KCiAgICAjIyMgSW5wdXQgKHJlcXVlc3Qg +SlNPTiBib2R5KQoKICAgIE5hbWUgfCBUeXBlIHwgRGVzY3JpcHRpb24KICAg +IC0tLS0tfC0tLS0tLXwtLS0tLS0tLS0tLS0tLQogICAgYG5hbWVgfGB0eXBl +YCB8IERlc2NyaXB0aW9uLgoKICAgICMjIyBSZXNwb25zZQoKICAgIDwlPSBo +ZWFkZXJzIDIwMCwgOnBhZ2luYXRpb24gPT4gZGVmYXVsdF9wYWdpbmF0aW9u +X3JlbHMsICdYLUN1c3RvbS1IZWFkZXInID0+ICJ2YWx1ZSIgJT4KICAgIDwl +PSBqc29uIDpyZXNvdXJjZV9uYW1lICU+CgoqKk5vdGUqKjogV2UncmUgdXNp +bmcgW0tyYW1kb3duIE1hcmtkb3duIGV4dGVuc2lvbnNdKGh0dHA6Ly9rcmFt +ZG93bi5nZXR0YWxvbmcub3JnL3N5bnRheC5odG1sKSwgc3VjaCBhcyBkZWZp +bml0aW9uIGxpc3RzLgoKIyMjIEpTT04gUmVzcG9uc2VzCgpXZSBzcGVjaWZ5 +IHRoZSBKU09OIHJlc3BvbnNlcyBpbiBSdWJ5IHNvIHRoYXQgd2UgZG9uJ3Qg +aGF2ZSB0byB3cml0ZQp0aGVtIGJ5IGhhbmQgYWxsIG92ZXIgdGhlIGRvY3Mu +ICBZb3UgY2FuIHJlbmRlciB0aGUgSlNPTiBmb3IgYSByZXNvdXJjZQpsaWtl +IHRoaXM6CgpgYGBlcmIKPCU9IGpzb24gOmlzc3VlICU+CmBgYAoKVGhpcyBs +b29rcyB1cCBgR2l0SHViOjpSZXNvdXJjZXM6OklTU1VFYCBpbiBgbGliL3Jl +c291cmNlcy5yYmAuCgpTb21lIGFjdGlvbnMgcmV0dXJuIGFycmF5cy4gIFlv +dSBjYW4gbW9kaWZ5IHRoZSBKU09OIGJ5IHBhc3NpbmcgYSBibG9jazoKCmBg +YGVyYgo8JT0ganNvbig6aXNzdWUpIHsgfGhhc2h8IFtoYXNoXSB9ICU+CmBg +YAoKVGhlcmUgaXMgYWxzbyBhIHJha2UgdGFzayBmb3IgZ2VuZXJhdGluZyBK +U09OIGZpbGVzIGZyb20gdGhlIHNhbXBsZSByZXNwb25zZXMgaW4gdGhlIGRv +Y3VtZW50YXRpb246CgpgYGAgc2gKJCByYWtlIGdlbmVyYXRlX2pzb25fZnJv +bV9yZXNwb25zZXMKYGBgCgpUaGUgZ2VuZXJhdGVkIGZpbGVzIHdpbGwgZW5k +IHVwIGluICpqc29uLWR1bXAvKi4KCiMjIyBUZXJtaW5hbCBibG9ja3MKCllv +dSBjYW4gc3BlY2lmeSB0ZXJtaW5hbCBibG9ja3MgYnkgdXNpbmcgdGhlIGBj +b21tYW5kLWxpbmVgIHN5bnRheCBoaWdobGlnaHRpbmcuCgogICAgYGBgIGNv +bW1hbmQtbGluZQogICAgJCBjdXJsIGZvb2JhcgogICAgYGBgCgpZb3UgY2Fu +IHVzZSBjZXJ0YWluIGNoYXJhY3RlcnMsIGxpa2UgYCRgIGFuZCBgI2AsIHRv +IGVtcGhhc2l6ZSBkaWZmZXJlbnQgcGFydHMKb2YgY29tbWFuZHMuCgogICAg +YGBgIGNvbW1hbmQtbGluZQogICAgIyBjYWxsIGZvb2JhcgogICAgJCBjdXJs +IDxlbT5mb29iYXI8ZW0+CiAgICAuLi4uCiAgICBgYGAKCkZvciBtb3JlIGlu +Zm9ybWF0aW9uLCBzZWUgW3RoZSByZWZlcmVuY2UgZG9jdW1lbnRhdGlvbl0o +aHR0cHM6Ly9naXRodWIuY29tL2dqdG9yaWtpYW4vZXh0ZW5kZWQtbWFya2Rv +d24tZmlsdGVyI2NvbW1hbmQtbGluZS1oaWdobGlnaHRpbmcpLgoKIyMgTGlj +ZW5zZXMKClRoZSBjb2RlIHRvIGdlbmVyYXRlIHRoZSBzaXRlIChldmVyeXRo +aW5nIGV4Y2x1ZGluZyB0aGUgYXNzZXRzLCBjb250ZW50LAphbmQgbGF5b3V0 +cyBkaXJlY3RvcmllcykgYXMgd2VsbCBhcyB0aGUgY29kZSBzYW1wbGVzIG9u +IHRoZSBzaXRlIGFyZQpsaWNlbnNlZCB1bmRlcgpbQ0MwLTEuMF0oaHR0cHM6 +Ly9jcmVhdGl2ZWNvbW1vbnMub3JnL3B1YmxpY2RvbWFpbi96ZXJvLzEuMC9s +ZWdhbGNvZGUpLgpDQzAgd2FpdmVzIGFsbCBjb3B5cmlnaHQgcmVzdHJpY3Rp +b25zIGJ1dCBkb2VzIG5vdCBncmFudCB5b3UgYW55IHRyYWRlbWFyawpwZXJt +aXNzaW9ucy4KClNpdGUgY29udGVudCAoZXZlcnl0aGluZyBpbiB0aGUgYXNz +ZXRzLCBjb250ZW50LCBhbmQgbGF5b3V0cyBkaXJlY3RvcmllcywKZXhjbHVk +aW5nIGZpbGVzIHVuZGVyIG9wZW4gc291cmNlIGxpY2Vuc2VzIGluZGl2aWR1 +YWxseSBtYXJrZWQpIGlzIGxpY2Vuc2VkCnVuZGVyIFtDQy1CWS00LjBdKGh0 +dHBzOi8vY3JlYXRpdmVjb21tb25zLm9yZy9saWNlbnNlcy9ieS80LjAvKS4g +Q0MtQlktNC4wCmdpdmVzIHlvdSBwZXJtaXNzaW9uIHRvIHVzZSBjb250ZW50 +IGZvciBhbG1vc3QgYW55IHB1cnBvc2UgYnV0IGRvZXMgbm90IGdyYW50Cnlv +dSBhbnkgdHJhZGVtYXJrIHBlcm1pc3Npb25zLCBzbyBsb25nIGFzIHlvdSBu +b3RlIHRoZSBsaWNlbnNlIGFuZCBnaXZlIGNyZWRpdCwKc3VjaCBhcyBmb2xs +b3dzOgoKPiBDb250ZW50IGJhc2VkIG9uCj4gPGEgaHJlZj0iaHR0cHM6Ly9n +aXRodWIuY29tL2dpdGh1Yi9kZXZlbG9wZXIuZ2l0aHViLmNvbSI+ZGV2ZWxv +cGVyLmdpdGh1Yi5jb208L2E+Cj4gdXNlZCB1bmRlciB0aGUKPiA8YSBocmVm +PSJodHRwczovL2NyZWF0aXZlY29tbW9ucy5vcmcvbGljZW5zZXMvYnkvNC4w +LyI+Q0MtQlktNC4wPC9hPgo+IGxpY2Vuc2UuPC9hPgoKVGhpcyBtZWFucyB5 +b3UgY2FuIHVzZSB0aGUgY29kZSBhbmQgY29udGVudCBpbiB0aGlzIHJlcG9z +aXRvcnkgZXhjZXB0IGZvcgpHaXRIdWIgdHJhZGVtYXJrcyBpbiB5b3VyIG93 +biBwcm9qZWN0cy4KCldoZW4geW91IGNvbnRyaWJ1dGUgdG8gdGhpcyByZXBv +c2l0b3J5IHlvdSBhcmUgZG9pbmcgc28gdW5kZXIgdGhlIGFib3ZlCmxpY2Vu +c2VzLgo= From a03030dea7be744a3feff20ea29f51783f37a47f Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 8 Sep 2016 18:27:26 -0500 Subject: [PATCH 29/29] Update README --- README.md | 312 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 176 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index 620e7a2091..d73feafde0 100644 --- a/README.md +++ b/README.md @@ -1,136 +1,176 @@ -IyBkZXZlbG9wZXIuZ2l0aHViLmNvbQoKKipOT1RFOiBUaGUgZGV2ZWxvcGVy -LmdpdGh1Yi5jb20gd2Vic2l0ZSBpcyBubyBsb25nZXIgb3Blbi1zb3VyY2Uu -KioKCldlIGhhdmUgbW92ZWQgdGhpcyByZXBvc2l0b3J5IGludG8gW291ciBn -aXRodWItYXJjaGl2ZSBvcmdhbml6YXRpb25dKGh0dHBzOi8vZ2l0aHViLmNv -bS9naXRodWItYXJjaGl2ZSkgdG8gc2lnbmlmeSB0aGF0IHdlIGFyZSBubyBs -b25nZXIgYWNjZXB0aW5nIG9wZW4tc291cmNlIGNvbnRyaWJ1dGlvbnMgdG8g -dGhpcyByZXBvc2l0b3J5LiBXZSB3YW50IHRvIHRoYW5rIHRoZSBodW5kcmVk -cyBvZiBjb250cmlidXRvcnMgZm9yIHRoZWlyIGFzc2lzdGFuY2Ugb3ZlciB0 -aGUgeWVhcnMuCgpUaGUgZGVjaXNpb24gdG8gY2xvc2Utc291cmNlIHRoZSBz -aXRlIHN0ZW1zIGZyb20gYSB2YXJpZXR5IG9mIHJlYXNvbnM6CgoxLiBXZSBh -Y3R1YWxseSBhbHJlYWR5IF9oYXZlXyBhIGNsb3NlLXNvdXJjZWQgc2l0ZSwg -d2hpY2ggaXMgd2hlcmUgd2Ugd3JvdGUgZG9jdW1lbnRhdGlvbiBmb3IgdW5y -ZWxlYXNlZCBmZWF0dXJlcy4gV2UgZGVzaWduZWQgYWRkaXRpb25hbCB0b29s -aW5nIHRvIHN1cHBvcnQgdGhpcyB3b3JrZmxvdywgYnV0IHVwZGF0aW5nIHRo -ZSBkb2N1bWVudGF0aW9uIGlzIGEgcHJvY2VzcyB3ZSdkIGxpa2UgdG8gc2lt -cGxpZnkuCjIuIFdlIGJlbGlldmUgdGhhdCBhbnkgb3Blbi1zb3VyY2UgcHJv -amVjdOKAlGJlIGl0IGRvY3VtZW50YXRpb24gb3Igc29mdHdhcmXigJRvdWdo -dCB0byBoYXZlIGRlZGljYXRlZCBtYWludGFpbmVycy4gSXQgYmVjYW1lIGRp -ZmZpY3VsdCB0byBrZWVwIHRoaXMgcmVwb3NpdG9yeSBvcGVuLXNvdXJjZSBi -ZWNhdXNlIGl0IHdhcyBtYWludGFpbmVkIGJ5IHRoZSBiZXN0IGVmZm9ydHMg -b2YgYSBzbWFsbCBncm91cCBvZiBwZW9wbGUuIENsb3NpbmcgdGhlIHNpdGUg -YWxsb3dzIHVzIHRvIGZvY3VzIG9uIHdoYXQncyBpbXBvcnRhbnQsIHdpdGhv -dXQgZmVlbGluZyBndWlsdHkgYXQgbWlzc2luZyByZXZpZXdzIGZyb20gb3Bl -bi1zb3VyY2UgY29udHJpYnV0b3JzLgoKV2UgdGhpbmsgdGhhdCB0aGUgdG9v -bGluZyB3ZSB1c2VkIHRvIGJ1aWxkIHRoaXMgc2l0ZSBpcyBwcmV0dHkgaW50 -ZXJlc3RpbmcsIHNvIHdlJ3JlIG5vdCBnZXR0aW5nIHJpZCBvZiBldmVyeXRo -aW5nLiBXZSBob3BlIHRoYXQgd2hhdCByZW1haW5zIGNhbiBiZSB1c2VkIGFz -IGEgc291cmNlIG9mIGluc3BpcmF0aW9uIGZvciB5b3VyIG93biBzdGF0aWMg -c2l0ZS4KCklmIHlvdSBmaW5kIHNvbWV0aGluZyB0aGF0IG5lZWRzIHRvIGJl -IGZpeGVkLCB5b3UgY2FuIGFsd2F5cyBbY29udGFjdCBvdXIgdGVycmlmaWMg -U3VwcG9ydCB0ZWFtXShodHRwczovL2dpdGh1Yi5jb20vY29udGFjdD9mb3Jt -JTVCc3ViamVjdCU1RD1Nb3ZpbmcrZGV2ZWxvcGVyLmdpdGh1Yi5jb20rdG8r -Z2l0aHViLWFyY2hpdmUpLgoKVGhhbmsgeW91IQoKKiAqICoKClRoaXMgd2Fz -IHRoZSBHaXRIdWIgQVBJIGRvY3VtZW50YXRpb24sIGJ1aWx0IHdpdGggW05h -bm9jXVtuYW5vY10uCgojIyBEZXZlbG9wbWVudAoKWW91IGNhbiBmZXRjaCB0 -aGUgbGF0ZXN0IGRlcGVuZGVuY2llcyBieSBvcGVuaW5nIHRoZSBjb21tYW5k -IGxpbmUgYW5kIHJ1bm5pbmcgYHNjcmlwdC9ib290c3RyYXBgOgoKYGBgIHNo -CiQgc2NyaXB0L2Jvb3RzdHJhcAo9PT4gSW5zdGFsbGluZyBnZW0gZGVwZW5k -ZW5jaWVz4oCmCj09PiBJbnN0YWxsaW5nIG5wbSBkZXBlbmRlbmNpZXPigKYK -YGBgCgpZb3UnbGwgbmVlZCBSdWJ5IGFuZCBOb2RlIGluc3RhbGxlZCBvbiB5 -b3VyIHN5c3RlbS4gVGhlIHJlcXVpcmVkIHZlcnNpb25zIGZvciBlYWNoIG9m -IHRoZXNlIGxhbmd1YWdlcyBjYW4gYmUgZm91bmQgaW4gdGhlICoucnVieS12 -ZXJzaW9uKiBhbmQgKnBhY2thZ2UuanNvbiogZmlsZXMsIHJlc3BlY3RpdmVs -eS4KCllvdSBjYW4gcnVuIGBidW5kbGUgZXhlYyByYWtlIGJ1aWxkYCB0byBn -ZW5lcmF0ZSB0aGUgc2l0ZSwgYnV0IGl0J3Mgb2Z0ZW4gbW9yZSB1c2VmdWwK -dG8gc2ltcGx5IGJ1aWxkIHRoZSBzZXJ2ZXIgKmFuZCogc3RhcnQgdGhlIHNp -dGUgYXQgdGhlIHNhbWUgdGltZS4KCk5hbm9jIGNvbXBpbGVzIHRoZSBzaXRl -IGludG8gc3RhdGljIGZpbGVzIGxpdmluZyBpbiBgb3V0cHV0YC4gIEl0J3MK -c21hcnQgZW5vdWdoIG5vdCB0byB0cnkgdG8gY29tcGlsZSB1bmNoYW5nZWQg -ZmlsZXMuCgpZb3UgY2FuIHN0YXJ0IHRoZSBzaXRlIHdpdGggYHNjcmlwdC9z -ZXJ2ZXJgOgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlcgpMb2FkaW5nIHNpdGUg -ZGF0YS4uLgpDb21waWxpbmcgc2l0ZS4uLgogICBjcmVhdGUgICAgIFswLjI4 -c10gIG91dHB1dC9pbmRleC5odG1sCiAgIGNyZWF0ZSAgICAgWzEuMzFzXSAg -b3V0cHV0L3YzL2dpc3RzL2NvbW1lbnRzL2luZGV4Lmh0bWwKICAgaWRlbnRp -Y2FsICBbMS45MnNdICBvdXRwdXQvdjMvZ2lzdHMvaW5kZXguaHRtbAogICBp -ZGVudGljYWwgIFswLjI1c10gIG91dHB1dC92My9pc3N1ZXMvY29tbWVudHMv -aW5kZXguaHRtbAogICB1cGRhdGUgICAgIFswLjk5c10gIG91dHB1dC92My9p -c3N1ZXMvbGFiZWxzL2luZGV4Lmh0bWwKICAgdXBkYXRlICAgICBbMC4wNXNd -ICBvdXRwdXQvdjMvaW5kZXguaHRtbAogICDigKYKClNpdGUgY29tcGlsZWQg -aW4gNS44MXMuCmBgYAoKVGhlIHNpdGUgaXMgaG9zdGVkIGF0IGBodHRwOi8v -bG9jYWxob3N0OjQwMDBgLgoKTmFub2MgaGFzIFtzb21lIG5pY2UgZG9jdW1l -bnRhdGlvbl0oaHR0cDovL25hbm9jLndzL2RvY3MvdHV0b3JpYWwvKSB0byBn -ZXQgeW91IHN0YXJ0ZWQuICBUaG91Z2ggaWYgeW91J3JlIG1haW5seSBjb25j -ZXJuZWQgd2l0aCBlZGl0aW5nIG9yIGFkZGluZyBjb250ZW50LCB5b3Ugd29u -J3QgbmVlZCB0byBrbm93IG11Y2ggYWJvdXQgTmFub2MuCgpbbmFub2NdOiBo -dHRwOi8vbmFub2Mud3MvCgojIyMgRW50ZXJwcmlzZQoKVG8gZ2VuZXJhdGUg -dGhlIGAvZW50ZXJwcmlzZWAgdmVyc2lvbnMsIHBhc3MgaW4gdGhlIEVudGVy -cHJpc2UgdmVyc2lvbiB0byBgc2NyaXB0L3NlcnZlcmAuIEZvciBleGFtcGxl -OgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlciAyLjYKYGBgCgpOb3RlIHRoYXQg -bGl2ZSByZWxvYWRpbmcgaXMgbm90IGF2YWlsYWJsZSBmb3IgRW50ZXJwcmlz -ZSBkb2N1bWVudGF0aW9uLgoKIyMgU3R5bGVndWlkZQoKTm90IHN1cmUgaG93 -IHRvIHN0cnVjdHVyZSB0aGUgZG9jcz8gIEhlcmUncyB3aGF0IHRoZSBzdHJ1 -Y3R1cmUgb2YgdGhlCkFQSSBkb2NzIHNob3VsZCBsb29rIGxpa2U6CgogICAg -IyBBUEkgdGl0bGUKCiAgICB7OnRvY30KCiAgICAjIyBBUEkgZW5kcG9pbnQg -dGl0bGUKCiAgICAgICAgW1ZFUkJdIC9wYXRoL3RvL2VuZHBvaW50CgogICAg -IyMjIFBhcmFtZXRlcnMKCiAgICBOYW1lIHwgVHlwZSB8IERlc2NyaXB0aW9u -CiAgICAtLS0tLXwtLS0tLS18LS0tLS0tLS0tLS0tLS0KICAgIGBuYW1lYHxg -dHlwZWAgfCBEZXNjcmlwdGlvbi4KCiAgICAjIyMgSW5wdXQgKHJlcXVlc3Qg -SlNPTiBib2R5KQoKICAgIE5hbWUgfCBUeXBlIHwgRGVzY3JpcHRpb24KICAg -IC0tLS0tfC0tLS0tLXwtLS0tLS0tLS0tLS0tLQogICAgYG5hbWVgfGB0eXBl -YCB8IERlc2NyaXB0aW9uLgoKICAgICMjIyBSZXNwb25zZQoKICAgIDwlPSBo -ZWFkZXJzIDIwMCwgOnBhZ2luYXRpb24gPT4gZGVmYXVsdF9wYWdpbmF0aW9u -X3JlbHMsICdYLUN1c3RvbS1IZWFkZXInID0+ICJ2YWx1ZSIgJT4KICAgIDwl -PSBqc29uIDpyZXNvdXJjZV9uYW1lICU+CgoqKk5vdGUqKjogV2UncmUgdXNp -bmcgW0tyYW1kb3duIE1hcmtkb3duIGV4dGVuc2lvbnNdKGh0dHA6Ly9rcmFt -ZG93bi5nZXR0YWxvbmcub3JnL3N5bnRheC5odG1sKSwgc3VjaCBhcyBkZWZp -bml0aW9uIGxpc3RzLgoKIyMjIEpTT04gUmVzcG9uc2VzCgpXZSBzcGVjaWZ5 -IHRoZSBKU09OIHJlc3BvbnNlcyBpbiBSdWJ5IHNvIHRoYXQgd2UgZG9uJ3Qg -aGF2ZSB0byB3cml0ZQp0aGVtIGJ5IGhhbmQgYWxsIG92ZXIgdGhlIGRvY3Mu -ICBZb3UgY2FuIHJlbmRlciB0aGUgSlNPTiBmb3IgYSByZXNvdXJjZQpsaWtl -IHRoaXM6CgpgYGBlcmIKPCU9IGpzb24gOmlzc3VlICU+CmBgYAoKVGhpcyBs -b29rcyB1cCBgR2l0SHViOjpSZXNvdXJjZXM6OklTU1VFYCBpbiBgbGliL3Jl -c291cmNlcy5yYmAuCgpTb21lIGFjdGlvbnMgcmV0dXJuIGFycmF5cy4gIFlv -dSBjYW4gbW9kaWZ5IHRoZSBKU09OIGJ5IHBhc3NpbmcgYSBibG9jazoKCmBg -YGVyYgo8JT0ganNvbig6aXNzdWUpIHsgfGhhc2h8IFtoYXNoXSB9ICU+CmBg -YAoKVGhlcmUgaXMgYWxzbyBhIHJha2UgdGFzayBmb3IgZ2VuZXJhdGluZyBK -U09OIGZpbGVzIGZyb20gdGhlIHNhbXBsZSByZXNwb25zZXMgaW4gdGhlIGRv -Y3VtZW50YXRpb246CgpgYGAgc2gKJCByYWtlIGdlbmVyYXRlX2pzb25fZnJv -bV9yZXNwb25zZXMKYGBgCgpUaGUgZ2VuZXJhdGVkIGZpbGVzIHdpbGwgZW5k -IHVwIGluICpqc29uLWR1bXAvKi4KCiMjIyBUZXJtaW5hbCBibG9ja3MKCllv -dSBjYW4gc3BlY2lmeSB0ZXJtaW5hbCBibG9ja3MgYnkgdXNpbmcgdGhlIGBj -b21tYW5kLWxpbmVgIHN5bnRheCBoaWdobGlnaHRpbmcuCgogICAgYGBgIGNv -bW1hbmQtbGluZQogICAgJCBjdXJsIGZvb2JhcgogICAgYGBgCgpZb3UgY2Fu -IHVzZSBjZXJ0YWluIGNoYXJhY3RlcnMsIGxpa2UgYCRgIGFuZCBgI2AsIHRv -IGVtcGhhc2l6ZSBkaWZmZXJlbnQgcGFydHMKb2YgY29tbWFuZHMuCgogICAg -YGBgIGNvbW1hbmQtbGluZQogICAgIyBjYWxsIGZvb2JhcgogICAgJCBjdXJs -IDxlbT5mb29iYXI8ZW0+CiAgICAuLi4uCiAgICBgYGAKCkZvciBtb3JlIGlu -Zm9ybWF0aW9uLCBzZWUgW3RoZSByZWZlcmVuY2UgZG9jdW1lbnRhdGlvbl0o -aHR0cHM6Ly9naXRodWIuY29tL2dqdG9yaWtpYW4vZXh0ZW5kZWQtbWFya2Rv -d24tZmlsdGVyI2NvbW1hbmQtbGluZS1oaWdobGlnaHRpbmcpLgoKIyMgTGlj -ZW5zZXMKClRoZSBjb2RlIHRvIGdlbmVyYXRlIHRoZSBzaXRlIChldmVyeXRo -aW5nIGV4Y2x1ZGluZyB0aGUgYXNzZXRzLCBjb250ZW50LAphbmQgbGF5b3V0 -cyBkaXJlY3RvcmllcykgYXMgd2VsbCBhcyB0aGUgY29kZSBzYW1wbGVzIG9u -IHRoZSBzaXRlIGFyZQpsaWNlbnNlZCB1bmRlcgpbQ0MwLTEuMF0oaHR0cHM6 -Ly9jcmVhdGl2ZWNvbW1vbnMub3JnL3B1YmxpY2RvbWFpbi96ZXJvLzEuMC9s -ZWdhbGNvZGUpLgpDQzAgd2FpdmVzIGFsbCBjb3B5cmlnaHQgcmVzdHJpY3Rp -b25zIGJ1dCBkb2VzIG5vdCBncmFudCB5b3UgYW55IHRyYWRlbWFyawpwZXJt -aXNzaW9ucy4KClNpdGUgY29udGVudCAoZXZlcnl0aGluZyBpbiB0aGUgYXNz -ZXRzLCBjb250ZW50LCBhbmQgbGF5b3V0cyBkaXJlY3RvcmllcywKZXhjbHVk -aW5nIGZpbGVzIHVuZGVyIG9wZW4gc291cmNlIGxpY2Vuc2VzIGluZGl2aWR1 -YWxseSBtYXJrZWQpIGlzIGxpY2Vuc2VkCnVuZGVyIFtDQy1CWS00LjBdKGh0 -dHBzOi8vY3JlYXRpdmVjb21tb25zLm9yZy9saWNlbnNlcy9ieS80LjAvKS4g -Q0MtQlktNC4wCmdpdmVzIHlvdSBwZXJtaXNzaW9uIHRvIHVzZSBjb250ZW50 -IGZvciBhbG1vc3QgYW55IHB1cnBvc2UgYnV0IGRvZXMgbm90IGdyYW50Cnlv -dSBhbnkgdHJhZGVtYXJrIHBlcm1pc3Npb25zLCBzbyBsb25nIGFzIHlvdSBu -b3RlIHRoZSBsaWNlbnNlIGFuZCBnaXZlIGNyZWRpdCwKc3VjaCBhcyBmb2xs -b3dzOgoKPiBDb250ZW50IGJhc2VkIG9uCj4gPGEgaHJlZj0iaHR0cHM6Ly9n -aXRodWIuY29tL2dpdGh1Yi9kZXZlbG9wZXIuZ2l0aHViLmNvbSI+ZGV2ZWxv -cGVyLmdpdGh1Yi5jb208L2E+Cj4gdXNlZCB1bmRlciB0aGUKPiA8YSBocmVm -PSJodHRwczovL2NyZWF0aXZlY29tbW9ucy5vcmcvbGljZW5zZXMvYnkvNC4w -LyI+Q0MtQlktNC4wPC9hPgo+IGxpY2Vuc2UuPC9hPgoKVGhpcyBtZWFucyB5 -b3UgY2FuIHVzZSB0aGUgY29kZSBhbmQgY29udGVudCBpbiB0aGlzIHJlcG9z -aXRvcnkgZXhjZXB0IGZvcgpHaXRIdWIgdHJhZGVtYXJrcyBpbiB5b3VyIG93 -biBwcm9qZWN0cy4KCldoZW4geW91IGNvbnRyaWJ1dGUgdG8gdGhpcyByZXBv -c2l0b3J5IHlvdSBhcmUgZG9pbmcgc28gdW5kZXIgdGhlIGFib3ZlCmxpY2Vu -c2VzLgo= +# developer.github.com + +**NOTE: The developer.github.com website is no longer open-source.** + +We have moved this repository into [our github-archive organization](https://github.com/github-archive) to signify that we are no longer accepting open-source contributions to this repository. We want to thank the hundreds of contributors for their assistance over the years. + +The decision to close-source the site stems from a variety of reasons: + +1. We actually already _have_ a close-sourced site, which is where we wrote documentation for unreleased features. We designed additional tooling to support this workflow, but updating the documentation is a process we'd like to simplify. +2. We believe that any open-source project—be it documentation or software—ought to have dedicated maintainers. It became difficult to keep this repository open-source because it was maintained by the best efforts of a small group of people. Closing the site allows us to focus on what's important, without feeling guilty at missing reviews from open-source contributors. + +We think that the tooling we used to build this site is pretty interesting, so we're not getting rid of everything. We hope that what remains can be used as a source of inspiration for your own static site. + +If you find something that needs to be fixed, you can always [contact our terrific Support team](https://github.com/contact?form%5Bsubject%5D=Moving+developer.github.com+to+github-archive). + +Thank you! + +* * * + +This was the GitHub API documentation, built with [Nanoc][nanoc]. + +## Development + +You can fetch the latest dependencies by opening the command line and running `script/bootstrap`: + +``` sh +$ script/bootstrap +==> Installing gem dependencies… +==> Installing npm dependencies… +``` + +You'll need Ruby and Node installed on your system. The required versions for each of these languages can be found in the *.ruby-version* and *package.json* files, respectively. + +You can run `bundle exec rake build` to generate the site, but it's often more useful +to simply build the server *and* start the site at the same time. + +Nanoc compiles the site into static files living in `output`. It's +smart enough not to try to compile unchanged files. + +You can start the site with `script/server`: + +``` sh +$ script/server +Loading site data... +Compiling site... + create [0.28s] output/index.html + create [1.31s] output/v3/gists/comments/index.html + identical [1.92s] output/v3/gists/index.html + identical [0.25s] output/v3/issues/comments/index.html + update [0.99s] output/v3/issues/labels/index.html + update [0.05s] output/v3/index.html + … + +Site compiled in 5.81s. +``` + +The site is hosted at `http://localhost:4000`. + +Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about Nanoc. + +[nanoc]: http://nanoc.ws/ + +### Enterprise + +To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: + +``` sh +$ script/server 2.6 +``` + +Note that live reloading is not available for Enterprise documentation. + +## Styleguide + +Not sure how to structure the docs? Here's what the structure of the +API docs should look like: + + # API title + + {:toc} + + ## API endpoint title + + [VERB] /path/to/endpoint + + ### Parameters + + Name | Type | Description + -----|------|-------------- + `name`|`type` | Description. + + ### Input (request JSON body) + + Name | Type | Description + -----|------|-------------- + `name`|`type` | Description. + + ### Response + + <%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %> + <%= json :resource_name %> + +**Note**: We're using [Kramdown Markdown extensions](http://kramdown.gettalong.org/syntax.html), such as definition lists. + +### JSON Responses + +We specify the JSON responses in Ruby so that we don't have to write +them by hand all over the docs. You can render the JSON for a resource +like this: + +```erb +<%= json :issue %> +``` + +This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`. + +Some actions return arrays. You can modify the JSON by passing a block: + +```erb +<%= json(:issue) { |hash| [hash] } %> +``` + +There is also a rake task for generating JSON files from the sample responses in the documentation: + +``` sh +$ rake generate_json_from_responses +``` + +The generated files will end up in *json-dump/*. + +### Terminal blocks + +You can specify terminal blocks by using the `command-line` syntax highlighting. + + ``` command-line + $ curl foobar + ``` + +You can use certain characters, like `$` and `#`, to emphasize different parts +of commands. + + ``` command-line + # call foobar + $ curl foobar + .... + ``` + +For more information, see [the reference documentation](https://github.com/gjtorikian/extended-markdown-filter#command-line-highlighting). + +## Licenses + +The code to generate the site (everything excluding the assets, content, +and layouts directories) as well as the code samples on the site are +licensed under +[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode). +CC0 waives all copyright restrictions but does not grant you any trademark +permissions. + +Site content (everything in the assets, content, and layouts directories, +excluding files under open source licenses individually marked) is licensed +under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). CC-BY-4.0 +gives you permission to use content for almost any purpose but does not grant +you any trademark permissions, so long as you note the license and give credit, +such as follows: + +> Content based on +> developer.github.com +> used under the +> CC-BY-4.0 +> license. + +This means you can use the code and content in this repository except for +GitHub trademarks in your own projects. + +When you contribute to this repository you are doing so under the above +licenses.