describe new mime type stuff, add a real change log

technoweenie · technoweenie · commit 4caab67b753c · 2011-10-31T12:26:35.000-06:00
diff --git a/content/index.md b/content/index.md
@@ -10,34 +10,6 @@ you have any problems or requests please contact
 
 For the new API v3, start browsing the resources on the right >>
 
-## Breaking BETA Changes
+View the [API Changelog](/v3/changelog) for information on existing and
+planned changes to the API.
 
-We're making some small tweaks to the API during the BETA phase.  Old
-behavior will be supported until the dates listed below. Please be sure
-to update your app in time.
-
-### Behavior due to be removed by July 20th:
-
-* `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
-  returned.
-
-### Changelog for breaking changes
-
-#### Removed on June 15th:
-
-* `gravatar_url` is being deprecated in favor of `avatar_url` for all
-  responses that include users or orgs. A default size is no longer
-  included in the url.
-* Creating new gists (both anonymously and with an authenticated user)
-  should use `POST /gists` from now on. `POST /users/:user/gists` is no
-  longer supported.
-
-#### Removed on June 1st:
-
-* Removed support for PUT verb on update requests. Use POST or PATCH
-  instead.
-* Removed `.json` extension from all URLs.
-* No longer using the X-Next or X-Last headers. Pagination info is
-  returned in the Link header instead.
-* JSON-P response has completely changed to a more consistent format.
-* Starring gists now uses PUT verb (instead of POST) and returns 204.
diff --git a/content/v3/changelog.md b/content/v3/changelog.md
@@ -0,0 +1,43 @@
+---
+title: GitHub API Changelog
+---
+
+# Current Version
+
+The GitHub API version is currently in beta.  The Accept mime type is
+`application/vnd.github.beta+json`.  The `beta` mime type property will
+be valid until sometime in 2012.  A notice will be given closer to the
+actual date.
+
+We consider the beta API unbreakable, so please [file a support
+issue](https://github.com/contact) if you have problems.
+
+## Upcoming Version
+
+The API is expected to be finalized in late 2011.
+
+### Expected Changes
+
+* `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
+  returned.
+
+## Breaking Beta Changes
+
+#### Removed on June 15th:
+
+* `gravatar_url` is being deprecated in favor of `avatar_url` for all
+  responses that include users or orgs. A default size is no longer
+  included in the url.
+* Creating new gists (both anonymously and with an authenticated user)
+  should use `POST /gists` from now on. `POST /users/:user/gists` is no
+  longer supported.
+
+#### Removed on June 1st:
+
+* Removed support for PUT verb on update requests. Use POST or PATCH
+  instead.
+* Removed `.json` extension from all URLs.
+* No longer using the X-Next or X-Last headers. Pagination info is
+  returned in the Link header instead.
+* JSON-P response has completely changed to a more consistent format.
+* Starring gists now uses PUT verb (instead of POST) and returns 204.
diff --git a/content/v3/mime.md b/content/v3/mime.md
@@ -2,116 +2,85 @@
 title: Custom Mime Types | GitHub API
 ---
 
-# Custom Mime Types
+# GitHub Mime Types
 
 Custom mime types are used in the API to let consumers choose the format
 of the data they wish to receive. This is done by adding one or more of
 the following types to the `Accept` header when you make a request. Mime
 types are specific to resources, allowing them to change independently
 and support formats that other resources don't.
 
-## Issue
+All GitHub mime types look like this:
 
-The body of an issue can be written in [GitHub Flavored Markdown][gfm].
-These mime types are allowed:
+    application/vnd.github[.version].param[+json]
+
+The most basic mime types the API supports are:
+
+    application/json
+    application/vnd.github+json
+
+Neither of these specify a version, so you will always get the latest
+JSON representation of resources.  If you're building an application and
+care about the stability of the API, specify a version like so:
+
+    application/vnd.github.beta+json
+
+If you're specifying a property (such as full/raw/etc defined below),
+put the version before the property:
+
+    application/vnd.github.beta.raw+json
+
+For specifics on versions, check the [API changelog](/v3/changelog).
+
+## Comment Body Properties
+
+The body of a comments can be written in [GitHub Flavored Markdown][gfm].
+Issues, Issue Comments, Pull Request Comments, and Gist Comments all
+accept these same mime types:
 
 ### Raw
 
-    application/vnd.github-issue.raw+json
+    application/vnd.github.VERSION.raw+json
 
 Return the raw markdown body. Response will include `body`. This is the
 default if you do not pass any specific mime type.
 
 ### Text
 
-    application/vnd.github-issue.text+json
+    application/vnd.github.VERSION.text+json
 
 Return a text only representation of the markdown body. Response will
 include `body_text`.
 
 ### Html
 
-    application/vnd.github-issue.html+json
+    application/vnd.github.VERSION.html+json
 
 Return html rendered from the body's markdown. Response will include
 `body_html`.
 
 ### Full
 
-    application/vnd.github-issue.full+json
+    application/vnd.github.VERSION.full+json
 
 Return raw, text and html representations. Response will include `body`,
 `body_text`, and `body_html`:
 
-## Issue Comment
-
-The body of an issue comment can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
-    application/vnd.github-issuecomment.raw+json
-    application/vnd.github-issuecomment.text+json
-    application/vnd.github-issuecomment.html+json
-    application/vnd.github-issuecomment.full+json
-
-## Commit Comment
-
-The body of an commit comment can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
-    application/vnd.github-commitcomment.raw+json
-    application/vnd.github-commitcomment.text+json
-    application/vnd.github-commitcomment.html+json
-    application/vnd.github-commitcomment.full+json
-
-## Pull Request
-
-The body of an pull request can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
-    application/vnd.github-pull.raw+json
-    application/vnd.github-pull.text+json
-    application/vnd.github-pull.html+json
-    application/vnd.github-pull.full+json
-
-## Pull Request Comment
-
-The body of an pull request comment can also be written in [GitHub
-Flavored Markdown][gfm]. The semantics are identical to the Issue
-resource described above. These mime types are allowed:
-
-    application/vnd.github-pullcomment.raw+json
-    application/vnd.github-pullcomment.text+json
-    application/vnd.github-pullcomment.html+json
-    application/vnd.github-pullcomment.full+json
-
-## Gist Comment
-
-The body of an gist comment can also be written in [GitHub
-Flavored Markdown][gfm]. The semantics are identical to the Issue
-resource described above. These mime types are allowed:
-
-    application/vnd.github-gistcomment.raw+json
-    application/vnd.github-gistcomment.text+json
-    application/vnd.github-gistcomment.html+json
-    application/vnd.github-gistcomment.full+json
-
-## Git Blob
+## Git Blob Properties
 
 The following mime types are allowed when getting a blob:
 
 ### JSON
 
+    application/vnd.github.VERSION+json
     application/json
 
 Return JSON representation of the blob with `content` as a base64
 encoded string. This is the default if nothing is passed.
 
 ### Raw
 
-    application/vnd.github-blob.raw
+    application/vnd.github.VERSION.raw
 
 Return the raw blob data.
 
diff --git a/layouts/default.html b/layouts/default.html
@@ -43,6 +43,7 @@ <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/">Summary
             <ul class="js-guides">
               <li><a href="/v3/oauth/">OAuth</a></li>
               <li><a href="/v3/mime/">Mime Types</a></li>
+              <li><a href="/v3/changelog/">Changelog</a></li>
               <li><a href="/v3/libraries/">Libraries</a></li>
             </ul>
           </li>
