Introduce prototype for beta-to-v3 changelog

jasonrudolph · jasonrudolph · commit 67500ae2d294 · 2013-12-05T10:34:52.000-05:00
diff --git a/content/v3.md b/content/v3.md
@@ -14,12 +14,11 @@ This describes the resources that make up the official GitHub API v3. If you hav
 
     Accept: application/vnd.github.beta+json
 
-The GitHub API version is currently in beta.  [The `beta` media type](/v3/media/)
-property will be valid until sometime in 2013.  A notice will be given closer
-to the actual date.
+There are two versions of the GitHub API: `beta` and `v3`. (There are just a few [differences](/v3/media/#beta-to-v3-changelog) between these two versions.)
 
-We consider the "beta" API unchangeable.  [File a support issue](https://github.com/contact)
-if you have problems.
+By default, all requests receive the `beta` version. We encourage you to [request a specific version via the `Accept` header](/v3/media/#beta-v3-and-the-future).
+
+The `beta` API and `v3` API are both unchangeable. Please [file a support issue][support] if you have problems.
 
 ## Schema
 
diff --git a/content/v3/gists.md b/content/v3/gists.md
@@ -49,7 +49,11 @@ Name | Type | Description
 
     GET /gists/:id
 
-_Note_: When using the [v3 media type][2] the "user" field will become "owner"
+<div class="alert">
+  <p>
+    <strong>Note</strong>: When using the <a href="/v3/media/#beta-v3-and-the-future">v3 media type</a>, the <code>user</code> attribute is renamed to <code>owner</code>.
+  </p>
+</div>
 
 ### Response
 
@@ -168,4 +172,3 @@ including the filename with a `null` hash.
 <%= headers 204 %>
 
 [1]: /v3/oauth/#scopes
-[2]: /v3/media
diff --git a/content/v3/issues.md b/content/v3/issues.md
@@ -69,6 +69,12 @@ Name | Type | Description
 
     GET /repos/:owner/:repo/issues/:number
 
+<div class="alert">
+  <p>
+    <strong>Note</strong>: Every pull request is an issue, but not every issue is a pull request. When using the <a href="/v3/media/#beta-v3-and-the-future">v3 media type</a>, if the issue is not a pull request, the response omits the <code>pull_request</code> attribute.
+  </p>
+</div>
+
 ### Response
 
 <%= headers 200 %>
diff --git a/content/v3/media.md b/content/v3/media.md
@@ -53,8 +53,6 @@ for the `X-GitHub-Media-Type` header:
 ## Beta, v3, and the Future
 
 Ultimately, we aim for a version-less, [Hypermedia][hypermedia]-driven API.
-Before we get there, we [expect a few changes][expected-changes].
-
 In the mean time, if you don't specify a version in the `Accept` header, you'll
 get the `beta` version (as shown above) by default.
 
@@ -64,8 +62,31 @@ media type in the `Accept` header:
 
     application/vnd.github.v3
 
-Where there's a difference between the `beta` and `v3` representations, we'll
-strive to call out those differences.
+Check out the [full list of differences](#beta-to-v3-changelog) between `beta` and `v3` below.
+
+## Beta-to-v3 Changelog
+
+The v3 media type differs from the beta media type in just a few places:
+
+### Gist JSON
+
+For [Gists](/v3/gists/#get-a-single-gist), the v3 media type renames the `user` attribute to `owner`.
+
+### Issue JSON
+
+When an [issue](/v3/issues/#get-a-single-issue) is not a pull request, the v3 media type omits the `pull_request` attribute.
+
+### Repository JSON
+
+TODO
+
+### User JSON
+
+TODO
+
+### User Emails JSON
+
+TODO
 
 ## Comment Body Properties
 
