Clarify pagination

pengwynn · pengwynn · commit d0a7479c1104 · 2012-07-27T06:43:20.000-05:00
diff --git a/content/v3.md b/content/v3.md
@@ -176,7 +176,12 @@ resources, you can also set a custom page size up to 100 with the `?per_page` pa
 $ curl https://api.github.com/user/repos?page=2&per_page=100
 </pre>
 
-The pagination info is included in [the Link header](http://www.w3.org/Protocols/9707-link-header.html):
+The pagination info is included in [the Link
+header](http://www.w3.org/Protocols/9707-link-header.html). It is important to
+follow these Link header values instead of constructing your own URLs. In some
+instances, such as in the [Commits
+API](/v3/repos/commits/), pagination is based on
+SHA1 and not on page number.
 
     Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
       <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"
diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md
@@ -4,10 +4,17 @@ title: Repo Commits | GitHub API
 
 # Repo Commits API
 
+The Repo Commits API supports listing, viewing, and comparing commits in a repository.
+
 ## List commits on a repository
 
     GET /repos/:user/: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](http://developer.github.com/v3/#pagination)
+instead of constructing page links yourself.
+
 ### Parameters
 
 sha
