Merge branch 'master' into developer-next-groundwork

tobiasahlin · tobiasahlin · commit 58d0752a0de3 · 2013-11-04T18:03:52.000+01:00
Conflicts:
	content/index.md

Moved new deprecations section to v3.md
diff --git a/content/changes/2013-04-25-deprecating-merge-commit-sha.html b/content/changes/2013-04-25-deprecating-merge-commit-sha.html
@@ -16,7 +16,7 @@
 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
+[deprecated](/#deprecations) 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
diff --git a/content/guides/getting-started.md b/content/guides/getting-started.md
@@ -208,7 +208,7 @@ Most any meaningful use of the GitHub API will involve some level of Repository
 information. We can `GET` repository details in the same way we fetched user
 details earlier:
 
-      curl -i https://api.github.com/repos/twitter/bootstrap
+      curl -i https://api.github.com/repos/twbs/bootstrap
 
 In the same way, we can view repositories for the authenticated user:
 
diff --git a/content/index.md b/content/index.md
@@ -34,3 +34,4 @@ GitHub in your app</h1>
 		
 	</ul>
 </div>
+
diff --git a/content/v3.md b/content/v3.md
@@ -21,31 +21,60 @@ to the actual date.
 We consider the "beta" API unchangeable.  [File a support issue](https://github.com/contact)
 if you have problems.
 
-#### Expected Changes
-
-These changes are _not_ implemented, just planned for the next major API version.
-
-* `[ ]` Standardize on existing `*_url` attributes for hypermedia.  Remove all `_links`
-objects.
-* `[✓]` <del>The '/repos/:owner/:repo/hooks/:id/test' action becomes
-  '/repos/:owner/:repo/hooks/:id/tests'.</del>
-* `[✓]` <del>The '/gists/:id/fork' action becomes '/gists/:id/forks'.</del> 
-* `[ ]` Gist forks/history objects become separate API calls.
-* `[ ]` Gist files object is not returned on Gist listings.
-* `[ ]` Commit schema will change to be [more consistent](https://gist.github.com/3a2e5779588e21b0c0f3).
-* `[ ]` `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.
-* `[✓]` <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"`).
-* `[ ]` Remove the [Legacy Search API](/v3/search/legacy/).
-* `[ ]` Top-level `rate` hash on the [Rate Limit API](v3/rate_limit/) will no longer be returned.
+### Deprecations
+
+The following functionality is deprecated. For backwards compatibility purposes,
+API v3 will continue to provide this functionality. However, this deprecated
+functionality **will be removed** in the _next_ major version of the API.
+
+The recommendations below will help you prepare your application for the next major version of the API.
+
+1. Method: /gists/:id/fork
+: Recommendation: Use **/gists/:id/forks** (plural) instead.
+
+1. Method: /legacy/issues/search/:owner/:repository/:state/:keyword
+: Recommendation: Use [v3 Issue Search API](v3/search/#search-issues) instead.
+
+1. Method: /legacy/repos/search/:keyword
+: Recommendation: Use [v3 Repository Search API](/v3/search/#search-repositories) instead.
+
+1. Method: /legacy/user/search/:keyword
+: Recommendation: Use [v3 User Search API](/v3/search/#search-users) instead.
+
+1. Method: /legacy/user/email/:email
+: Recommendation: Use [v3 User Search API](/v3/search/#search-users) instead.
+
+1. Method: /repos/:owner/:repo/hooks/:id/test
+: Recommendation: Use **/repos/:owner/:repo/hooks/:id/tests** (plural) instead.
+
+1. Query parameters when POSTing to /repos/:owner/:repo/forks
+: Recommendation: Use JSON to POST to this method instead.
+
+1. Pull Request attribute: merge_commit_sha
+: Recommendation: [Do not use this attribute](/changes/2013-04-25-deprecating-merge-commit-sha/).
+
+1. Rate Limit attribute: rate
+: Recommendation: Use **resources["core"]** instead.
+
+1. Repository attribute: forks
+: Recommendation: Use **fork_count** instead.
+
+1. Repository attribute: master_branch
+: Recommendation: Use **default_branch** instead.
+
+1. Repository attribute: open_issues
+: Recommendation: Use **open_issues_count** instead.
+
+1. Repository attribute: public
+: Recommendation: When [creating a repository](/v3/repos/#create), use the
+  **private** attribute to indicate whether the repository should be public or
+  private. Do not use the **public** attribute.
+
+1. Repository attribute: watchers
+: Recommendation: Use **watchers_count** instead.
+
+1. User attribute: bio
+: Recommendation: Do not use this attribute. It is obsolete.
 
 ### Breaking Beta Changes
 
diff --git a/content/v3/media.md b/content/v3/media.md
@@ -137,4 +137,4 @@ The Commit, Commit Comparison, and Pull Request resources support
 [git-diff]: http://git-scm.com/docs/git-diff
 [git-patch]: http://git-scm.com/docs/git-format-patch
 [hypermedia]: /v3/#hypermedia
-[expected-changes]: /#expected-changes
+[expected-changes]: /#deprecations
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
@@ -72,7 +72,7 @@ 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
+however, this attribute is [deprecated](/#deprecations) and is scheduled for
 removal in the next version of the API. The Boolean `mergeable` attribute will
 remain to indicate whether the pull request can be automatically merged.
 
diff --git a/content/v3/rate_limit.md b/content/v3/rate_limit.md
@@ -43,7 +43,7 @@ all the _rest_ of the API.
 #### Deprecation Notice
 
 The `"rate"` hash (shown at the bottom of the response above) is
-[deprecated](/#expected-changes) and is scheduled for removal in the next
+[deprecated](/#deprecations) and is scheduled for removal in the next
 version of the API.
 
 If you're writing new API client code (or updating your existing code), you
diff --git a/content/v3/repos/contents.md b/content/v3/repos/contents.md
@@ -60,6 +60,11 @@ ref
 <%= headers 200 %>
 <%= json :directory_content %>
 
+Note: When listing the contents of a directory, submodules have their "type"
+specified as "file". Logically, the value *should* be "submodule". This behavior
+exists in API v3 [for backwards compatibility purposes](https://github.com/github/developer.github.com/commit/1b329b04cece9f3087faa7b1e0382317a9b93490).
+In the next major version of the API, the type will be returned as "submodule".
+
 ### Response if content is a symlink
 
 If the requested `:path` points to a symlink, and the symlink's target is a normal file in the repository, then the API responds with the content of the file (in the [format shown above](#response-if-content-is-a-file)).
diff --git a/content/v3/search.md b/content/v3/search.md
@@ -225,9 +225,9 @@ query might look something like this.
 
     https://api.github.com/search/issues?q=windows+label:bug+language:python+state:open&sort=created&order=asc
 
-In this query, we're searching for the keyword `win32`, within any open issue
+In this query, we're searching for the keyword `windows`, within any open issue
 that's labeled as `bug`. The search runs across repositories whose primary
-language is Ruby. We’re sorting by creation date in ascending order, so that
+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 %>
diff --git a/content/v3/search/legacy.md b/content/v3/search/legacy.md
@@ -14,7 +14,7 @@ v3. There should be no changes, other than the new URL and JSON output format.
 
 <div class="alert">
   <p>
-    The Legacy Search API (described below) is <a href="/#expected-changes">deprecated</a>
+    The Legacy Search API (described below) is <a href="/#deprecations">deprecated</a>
     and is scheduled for removal in the next version of the API.
 
     We recommend using the <a href="/v3/search/">v3 Search API</a> instead.
diff --git a/content/v3/users/emails.md b/content/v3/users/emails.md
@@ -18,11 +18,22 @@ This endpoint is accessible with the user:email scope.
 
 ### Response
 
+<div class="alert">
+  <p>
+    <strong>Deprecated</strong>: This response format is deprecated.
+    The API will remove support for this response format in the future.
+  </p>
+  <p>
+    We recommend that you start requesting the new response format as described
+    in the <a href="#future-response">Future Response</a> section below.
+  </p>
+</div>
+
 <%= headers 200 %>
 <%= json ["octocat@github.com", "support@github.com"] %>
 <br>
 
-#### Future response
+#### Future Response
 
 In the final version of the API, this method will return an array of hashes
 with extended information for each email address indicating if the address has
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -176,13 +176,10 @@ def text_html(response, status, head = {})
       "mirror_url"        => "git://git.example.com/octocat/Hello-World",
       "homepage"          => "https://github.com",
       "language"          => nil,
-      "forks"             => 9,
       "forks_count"       => 9,
-      "watchers"          => 80,
       "watchers_count"    => 80,
       "size"              => 108,
       "master_branch"     => 'master',
-      "open_issues"       => 0,
       "open_issues_count" => 0,
       "pushed_at"         => "2011-01-26T19:06:43Z",
       "created_at"        => "2011-01-26T19:01:12Z",
@@ -656,7 +653,8 @@ def text_html(response, status, head = {})
     }
 
     ISSUE_EVENT = {
-      "url" => "https://api.github.com/repos/octocat/Hello-World/issues/events/1",
+      "id"         => 1,
+      "url"        => "https://api.github.com/repos/octocat/Hello-World/issues/events/1",
       "actor"      => USER,
       "event"      => "closed",
       "commit_id"  => "6dcb09b5b57875f334f61aebed695e2e4193db5e",
@@ -846,9 +844,6 @@ def text_html(response, status, head = {})
           "language" => "Assembly",
           "forks_count" => 0,
           "open_issues_count" => 0,
-          "forks" => 0,
-          "open_issues" => 0,
-          "watchers" => 1,
           "master_branch" => "master",
           "default_branch" => "master",
           "score" => 10.309712

Original file line number	Diff line number	Diff line change
`@@ -34,3 +34,4 @@ GitHub in your app</h1>`
`34`	`34`
`35`	`35`	`</ul>`
`36`	`36`	`</div>`
	`37`	`+`
-Original file line number
+Diff line change
 <div class="alert">
   <p>
 -    The Legacy Search API (described below) is <a href="https://github.com/#expected-changes">deprecated</a>
 +    The Legacy Search API (described below) is <a href="https://github.com/#deprecations">deprecated</a>
     and is scheduled for removal in the next version of the API.
     We recommend using the <a href="/v3/search/">v3 Search API</a> instead.