Explain and deprecate the merge_commit_sha

jasonrudolph · jasonrudolph · commit 1460c72eaba3 · 2013-04-05T10:27:26.000-04:00
The merge_commit_sha is often misunderstood. It is internal GitHub
plumbing that just happens to be part of the public API. Explain it
(to reduce the confusion for the current version of the API), and
announce plans to remove it from the next version of the API.
diff --git a/content/index.md b/content/index.md
@@ -39,6 +39,8 @@ 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.
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
@@ -55,6 +55,15 @@ is `open`.
 <%= 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 Boolean `mergable` attribute indicates whether the pull request can be
+automatically merged. The `merge_commit_sha` attribute holds the SHA of the
+_test_ merge commit.
+
 ### Alternative Response Formats
 
 Pass the appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-requests) to fetch diff and patch formats.
