Sync changes from upstream repository

Hubot · Hubot · commit d4f010df97b0 · 2014-05-09T17:03:50.000Z
diff --git a/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md b/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md
@@ -0,0 +1,18 @@
+---
+kind: change
+title: Improved pagination for the Repository Commits API
+created_at: 2014-05-09
+author_name: izuzak
+---
+
+The [Repository Commits API](/v3/repos/commits/) now supports an additional approach for paginating [commit lists](/v3/repos/commits/#list-commits-on-a-repository). As of today, this endpoint supports the "standard" [`page` and `per_page` parameters](/v3/#pagination) for controlling pagination. This API now uses these parameters by default when constructing [page links](/v3/#pagination).
+
+# Improved results and increased consistency
+
+This new approach improves the reliability of this endpoint, which on rare occasions skipped some commits during pagination. This enhancement also increases the overall consistency of the API, as all endpoints now paginate resource lists the same way.
+
+# Old parameters still supported
+
+The old way of paginating, using `top`, `last_sha`, and `per_page` parameters, is still supported in API v3, but it will be removed in the [next major version of the API](https://developer.github.com/v3/versions/#v3-deprecations). API clients that are manually constructing URLs for pages should be modified to use the new parameters. Even better, API clients shouldn't construct URLs for pages manually, but should use [page links provided by the `Link` header](/guides/traversing-with-pagination/) in API responses.
+
+Since both the new and the old pagination parameters are still supported in API v3, API clients shouldn't notice any changes today. Still, if you notice any problems with this endpoint, please [let us know](https://github.com/contact?form%5Bsubject%5D=API:+Commits+pagination+improvements).
diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md
@@ -13,11 +13,6 @@ The Repo Commits API supports listing, viewing, and comparing commits in a repos
 
     GET /repos/:owner/:repo/commits
 
-_A special note on pagination:_ Due to the way Git works, commits are paginated
-based on SHA instead of page number. Please follow the link headers as outlined
-in the [pagination overview](https://developer.github.com/v3/#pagination)
-instead of constructing page links yourself.
-
 ### Parameters
 
 Name | Type | Description
@@ -32,9 +27,7 @@ Name | Type | Description
 ### Response
 
 <%=
-  headers 200, :pagination => {
-    :next => 'https://api.github.com/repositories/417862/commits?top=master&last_sha=4f9890864feb48296917c2fcf3682d8dc3adf16a'
-  }
+  headers 200, :pagination => default_pagination_rels
 %>
 <%= json(:commit) { |h| [h] } %>
 
diff --git a/content/v3/versions.md b/content/v3/versions.md
@@ -91,6 +91,10 @@ The recommendations below will help you prepare your application for the next ma
 1. User attribute: bio
 : Recommendation: Do not use this attribute. It is obsolete.
 
+1. Pagination parameters `top` and `sha` for method: /repos/:owner/:repo/commits
+: Recommendation: When fetching [the list of commits for a repository](/v3/repos/commits/#list-commits-on-a-repository)
+  use the [standard `per_page` and `page` parameters](/v3/#pagination) for pagination, instead of `per_page`,
+  `top`, and `sha`.
 
 # beta (Deprecated) {#beta}
 
