Improve description of deprecations

jasonrudolph · jasonrudolph · commit efb3972f194f · 2013-11-04T08:09:38.000-05:00
- Use a consistent format for all `v3` deprecations.
- Provide a recommendation for each `v3` deprecation.
- Move deprecation notice inline for `beta` /user/emails response format. This
  format will NOT be part of v3, so it doesn't belong in the v3 deprecations
  list.
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/index.md b/content/index.md
@@ -24,31 +24,51 @@ 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: master_branch
+: Recommendation: Use **default_branch** 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. 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
@@ -138,4 +138,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/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

-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.