Merge remote-tracking branch 'origin/master' into stats-api-docs

jasonrudolph · jasonrudolph · commit 1a0e54fc77e6 · 2013-05-01T13:27:28.000-04:00
diff --git a/content/changes/2013-04-24-user-agent-required.html b/content/changes/2013-04-24-user-agent-required.html
@@ -0,0 +1,16 @@
+---
+kind: change
+title: User Agent now mandatory
+created_at: 2013-04-24
+author_name: pengwynn
+---
+
+After an almost six week grace period, we're now enforcing the [User Agent
+header][1] for all API requests. Most HTTP libraries (including cURL)
+set this header by default. If you're experiencing an increase in `403`
+responses, be sure and check your code.
+
+[1]: /v3/#user-agent-required
+
+If you have any questions or feedback, please drop us a line at
+[support@github.com](mailto:support@github.com?subject=User Agent Requirement).
diff --git a/content/changes/2013-04-25-deprecating-merge-commit-sha.html b/content/changes/2013-04-25-deprecating-merge-commit-sha.html
@@ -0,0 +1,23 @@
+---
+kind: change
+title: Deprecating a Confusing Attribute in the Pull Request API
+created_at: 2013-04-25
+author_name: jasonrudolph
+---
+
+When you get the details for a Pull Request from the API, the
+[response](/v3/pulls/#get-a-single-pull-request) provides everything there is to
+know about that Pull Request. In addition to the useful information provided in
+the API response, the JSON also includes the `merge_commit_sha` attribute. This
+attribute is a frequent source of misunderstanding, and we aim to remove the
+confusion.
+
+To help current API consumers, we've [documented the
+attribute](/v3/pulls/#mergability) for improved understanding.
+
+To protect future API consumers from this confusion, we have
+[deprecated](/#expected-changes) the `merge_commit_sha` attribute, and we will
+remove it in the next major version of the API.
+
+As always, if you have any questions or feedback, please drop us a line at
+[support@github.com](mailto:support@github.com?subject=Deprecating merge_commit_sha).
diff --git a/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md b/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md
@@ -0,0 +1,39 @@
+---
+kind: change
+title: Improved Support for Submodules in the Repository Contents API
+created_at: 2013-04-30
+author_name: jasonrudolph
+---
+
+When you view a repository with a submodule on github.com, you get useful links and information for the submodule.
+
+[![Repository Contents with Submodule](/images/posts/submodule-links.png)][screenshot]
+
+Today we're making that data available in the [Repository Contents API][docs].
+
+<pre class="terminal">
+curl https://api.github.com/repos/jquery/jquery/contents/test/qunit
+
+{
+  "name": "qunit",
+  "path": "test/qunit",
+  "type": "submodule",
+  "submodule_git_url": "git://github.com/jquery/qunit.git",
+  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "size": 0,
+  "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+  "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "_links": {
+    "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
+  }
+}
+</pre>
+
+If you have any questions or feedback, please drop us a line at
+[support@github.com](mailto:support@github.com?subject=Submodules in Repository Contents API).
+
+[docs]: /v3/repos/contents/#get-contents
+[screenshot]: /images/posts/submodule-links.png
diff --git a/content/changes/2013-04-30-statuses-for-branches-and-tags.md b/content/changes/2013-04-30-statuses-for-branches-and-tags.md
@@ -0,0 +1,19 @@
+---
+kind: change
+title: Commit Statuses Now Available for Branches and Tags
+created_at: 2013-04-30
+author_name: foca
+---
+
+Last week we announced [support for build statuses in the branches page][blog].
+Now we are extending this to the API. The [API endpoint for commit statuses][doc]
+has been extended to allow branch and tag names, as well as commit SHAs.
+
+<pre class="terminal">
+curl https://api.github.com/repos/rails/rails/statuses/3-2-stable
+</pre>
+
+Enjoy.
+
+[blog]: https://github.com/blog/1484-check-the-status-of-your-branches
+[doc]: http://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref
diff --git a/content/index.md b/content/index.md
@@ -39,11 +39,14 @@ objects.
 * `[ ]` `master_branch` becomes `default_branch`.
 * `[ ]` `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
   returned.
+* `[ ]` `merge_commit_sha` on the [pull request API](/v3/pulls/#get-a-single-pull-request)
+  will no longer be returned.
 * `[ ]` Use the `private` attribute when creating a private repository,
   instead of setting `public` to false.
 * `[ ]` Use JSON to POST to the "repos/:owner/:repo/forks" endpoint, instead of a query string.
 * `[&#10003;]` <del>User Emails come back [as a hash][v3-email] instead of a string.</del>
 * `[ ]` Remove the unused "bio" field for Users.
+* `[ ]` When listing the contents of a directory in the [Repository Contents API](/v3/repos/contents/#get-contents), fix the `type` value returned for submodules: change the value to `"submodule"` (instead of `"file"`).
 
 ### Breaking Beta Changes
 
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
@@ -63,6 +63,18 @@ base
 <%= headers 200 %>
 <%= json :full_pull %>
 
+### Mergability
+
+Each time the pull request receives new commits, GitHub creates a merge commit
+to _test_ whether the pull request can be automatically merged into the base
+branch. (This _test_ commit is not added to the base branch or the head branch.)
+The `merge_commit_sha` attribute holds the SHA of the _test_ merge commit;
+however, this attribute is [deprecated](/#expected-changes) and is scheduled for
+removal in the next version of the API. The Boolean `mergable` attribute will
+remain to indicate whether the pull request can be automatically merged.
+
+### Alternative Response Formats
+
 Pass the appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-requests) to fetch diff and patch formats.
 
 ## Create a pull request
diff --git a/content/v3/repos/contents.md b/content/v3/repos/contents.md
@@ -30,15 +30,17 @@ ref
 
 ## Get contents
 
-This method returns the contents of any file or directory in a repository.
+This method returns the contents of a file or directory in a repository.
 
     GET /repos/:owner/:repo/contents/:path
 
 Files and symlinks support [a custom media type](#custom-media-types) for getting the raw content.
-Directories do _not_ support custom media types.
+Directories and submodules do _not_ support custom media types.
 
-*Note*: To get a repository's contents recursively, you can [recursively get
-the tree](/v3/git/trees/).
+*Notes*:
+
+- To get a repository's contents recursively, you can [recursively get the tree](/v3/git/trees/).
+- This API supports files up to 1 megabyte in size.
 
 ### Parameters
 
@@ -67,6 +69,16 @@ Otherwise, the API responds with a hash describing the symlink itself:
 <%= headers 200 %>
 <%= json :symlink_content %>
 
+### Response if content is a submodule
+
+<%= headers 200 %>
+<%= json :submodule_content %>
+
+The `submodule_git_url` identifies the location of the submodule repository, and the `sha` identifies a specific commit within the submodule repository.
+Git uses the given URL when cloning the submodule repository, and checks out the submodule at that specific commit.
+
+If the submodule repository is not hosted on github.com, the Git URLs (`git_url` and `_links["git"]`) and the github.com URLs (`html_url` and `_links["html"]`) will have null values.
+
 ## Get archive link
 
 This method will return a `302` to a URL to download a tarball
diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md
@@ -159,10 +159,12 @@ triggered on pushes.
 <%= headers 200 %>
 <%= json :hook %>
 
-## Test a hook
+## Test a `push` hook
 
 This will trigger the hook with the latest push to the current
-repository.
+repository if the hook is subscribed to `push` events. If the
+hook is not subscribed to `push` events, the server will respond
+with 204 but no test POST will be generated.
 
     POST /repos/:owner/:repo/hooks/:id/tests
 
diff --git a/content/v3/repos/statuses.md b/content/v3/repos/statuses.md
@@ -25,14 +25,14 @@ Note that the `repo:status` [OAuth scope](/v3/oauth/#scopes) grants targeted
 access to Statuses **without** also granting access to repo code, while the
 `repo` scope grants permission to code as well as statuses.
 
-## List Statuses for a specific SHA
+## List Statuses for a specific Ref
 
-    GET /repos/:owner/:repo/statuses/:sha
+    GET /repos/:owner/:repo/statuses/:ref
 
 ### Parameters
 
-sha
-: _Required_ **string** - Sha to list the statuses from
+ref
+: _Required_ **string** - Ref to list the statuses from. It can be a SHA, a branch name, or a tag name.
 
 ### Response
 
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -32,7 +32,9 @@ module Helpers
         :pezra        => 'f38112009dc16547051c8ac246cee443',
         :rick         => 'a44d5abad6e86cff4e34d9f0839535c9',
         :agh          => '6af915d3c6aa4ad30bbad43d8035fe10',
-        :Caged        => '97c3a8eea9b7eaa9e1e93ea3cd47399f'
+        :jasonrudolph => '592e1e6f041f9a4ec51846fd82013aea',
+        :Caged        => '97c3a8eea9b7eaa9e1e93ea3cd47399f',
+        :foca         => 'd0ca2bf32bda9e9ea8c4473ffc3aaa0d'
       }
 
       DefaultTimeFormat = "%B %-d, %Y".freeze
@@ -784,27 +786,27 @@ def text_html(response, status, head = {})
 
     TREE = {
       "sha"  => "9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
-      "url"  => "https://api.github.com/repo/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
+      "url"  => "https://api.github.com/repos/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
       "tree"  => [
         { "path" => "file.rb",
           "mode" => "100644",
           "type" => "blob",
           "size" => 30,
           "sha"  => "44b4fc6d56897b048c772eb4087f854f46256132",
-          "url"  => "https://api.github.com/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132",
+          "url"  => "https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132",
         },
         { "path" => "subdir",
           "mode" => "040000",
           "type" => "tree",
           "sha"  => "f484d249c660418515fb01c2b9662073663c242e",
-          "url"  => "https://api.github.com/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e"
+          "url"  => "https://api.github.com/repos/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e"
         },
         { "path" => "exec_file",
           "mode" => "100755",
           "type" => "blob",
           "size" => 75,
           "sha"  => "45b983be36b73c0788dc9cbcb76cbb80fc7bb057",
-          "url"  => "https://api.github.com/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057",
+          "url"  => "https://api.github.com/repos/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057",
         }
       ]
     }
@@ -1021,6 +1023,23 @@ def text_html(response, status, head = {})
       },
     }
 
+    SUBMODULE_CONTENT = {
+      "type" => "submodule",
+      "submodule_git_url" => "git://github.com/jquery/qunit.git",
+      "size" => 0,
+      "name" => "qunit",
+      "path" => "test/qunit",
+      "sha" => "6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "url" => "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+      "git_url" => "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "html_url" => "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "_links" => {
+        "git" => "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+        "self" => "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+        "html" => "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
+      }
+    }
+
     DIRECTORY_CONTENT = [
       {
         "type" => "file",
diff --git a/static/images/posts/submodule-links.png b/static/images/posts/submodule-links.png
