Update tests and javadoc

Author: bitwiseman

src/main/java/org/kohsuke/github/GHCompare.java

@@ -134,6 +134,15 @@ public Commit getMergeBaseCommit() {
     /**
      * Gets an array of commits.
      *
+     * By default, the commit list is limited to 250 results.
+     *
+     * Since
+     * <a href="https://github.blog/changelog/2021-03-22-compare-rest-api-now-supports-pagination/">2021-03-22</a>,
+     * compare supports pagination of commits. This makes the initial {@link GHCompare} response return faster and
+     * supports comparisons with more than 250 commits. To read commits progressively using pagination, set
+     * {@link GHRepository#setCompareUsePaginatedCommits(boolean)} to true before calling
+     * {@link GHRepository#getCompare(String, String)}.
+     *
      * @return A copy of the array being stored in the class.
      */
     public Commit[] getCommits() {
@@ -147,6 +156,15 @@ public Commit[] getCommits() {
     /**
      * Iterable of commits for this comparison.
      *
+     * By default, the commit list is limited to 250 results.
+     *
+     * Since
+     * <a href="https://github.blog/changelog/2021-03-22-compare-rest-api-now-supports-pagination/">2021-03-22</a>,
+     * compare supports pagination of commits. This makes the initial {@link GHCompare} response return faster and
+     * supports comparisons with more than 250 commits. To read commits progressively using pagination, set
+     * {@link GHRepository#setCompareUsePaginatedCommits(boolean)} to true before calling
+     * {@link GHRepository#getCompare(String, String)}.
+     *
      * @return iterable of commits
      */
     public PagedIterable<Commit> listCommits() {

src/main/java/org/kohsuke/github/GHRepository.java

@@ -1644,7 +1644,15 @@ public GHHook getHook(int id) throws IOException {
     }
 
     /**
+     * Sets {@link #getCompare(String, String)} to return a {@link GHCompare} that uses a paginated commit list instead
+     * of limiting to 250 results.
      *
+     * By default, {@link GHCompare} returns all commits in the comparison as part of the request, limited to 250
+     * results. More recently GitHub added the ability to return the commits as a paginated query allowing for more than
+     * 250 results.
+     *
+     * @param value
+     *            true if you want commits returned in paginated form.
      */
     public void setCompareUsePaginatedCommits(boolean value) {
         compareUsePaginatedCommits = value;

src/test/java/org/kohsuke/github/GHRepositoryTest.java

@@ -868,23 +868,26 @@ public void getLastCommitStatus() throws Exception {
     }
 
     @Test
-    public void getCommitsBetween() throws Exception {
+    public void listCommitsBetween() throws Exception {
         GHRepository repository = getRepository();
         int startingCount = mockGitHub.getRequestCount();
-        compareCommitsBetween(repository);
+        GHCompare compare = repository.getCompare("e46a9f3f2ac55db96de3c5c4706f2813b3a96465",
+                "8051615eff597f4e49f4f47625e6fc2b49f26bfc");
+        int actualCount = 0;
+        for (GHCompare.Commit item : compare.listCommits().withPageSize(5)) {
+            assertThat(item, notNullValue());
+            actualCount++;
+        }
+        assertThat(compare.getTotalCommits(), is(9));
+        assertThat(actualCount, is(9));
         assertThat(mockGitHub.getRequestCount(), equalTo(startingCount + 1));
     }
 
     @Test
-    public void getCommitsBetweenPaginated() throws Exception {
+    public void listCommitsBetweenPaginated() throws Exception {
         GHRepository repository = getRepository();
         int startingCount = mockGitHub.getRequestCount();
         repository.setCompareUsePaginatedCommits(true);
-        compareCommitsBetween(repository);
-        assertThat(mockGitHub.getRequestCount(), equalTo(startingCount + 3));
-    }
-
-    private void compareCommitsBetween(GHRepository repository) throws IOException {
         GHCompare compare = repository.getCompare("e46a9f3f2ac55db96de3c5c4706f2813b3a96465",
                 "8051615eff597f4e49f4f47625e6fc2b49f26bfc");
         int actualCount = 0;
@@ -894,5 +897,40 @@ private void compareCommitsBetween(GHRepository repository) throws IOException {
         }
         assertThat(compare.getTotalCommits(), is(9));
         assertThat(actualCount, is(9));
+        assertThat(mockGitHub.getRequestCount(), equalTo(startingCount + 3));
+    }
+
+    @Test
+    public void getCommitsBetweenOver250() throws Exception {
+        GHRepository repository = getRepository();
+        int startingCount = mockGitHub.getRequestCount();
+        GHCompare compare = repository.getCompare("4261c42949915816a9f246eb14c3dfd21a637bc2",
+                "94ff089e60064bfa43e374baeb10846f7ce82f40");
+        int actualCount = 0;
+        for (GHCompare.Commit item : compare.getCommits()) {
+            assertThat(item, notNullValue());
+            actualCount++;
+        }
+        assertThat(compare.getTotalCommits(), is(283));
+        assertThat(actualCount, is(250));
+        assertThat(mockGitHub.getRequestCount(), equalTo(startingCount + 1));
     }
+
+    @Test
+    public void getCommitsBetweenPaginatedOver250() throws Exception {
+        GHRepository repository = getRepository();
+        int startingCount = mockGitHub.getRequestCount();
+        repository.setCompareUsePaginatedCommits(true);
+        GHCompare compare = repository.getCompare("4261c42949915816a9f246eb14c3dfd21a637bc2",
+                "94ff089e60064bfa43e374baeb10846f7ce82f40");
+        int actualCount = 0;
+        for (GHCompare.Commit item : compare.getCommits()) {
+            assertThat(item, notNullValue());
+            actualCount++;
+        }
+        assertThat(compare.getTotalCommits(), is(283));
+        assertThat(actualCount, is(283));
+        assertThat(mockGitHub.getRequestCount(), equalTo(startingCount + 4));
+    }
+
 }

…tween/__files/orgs_hub4j-test-org-2.json …er250/__files/orgs_hub4j-test-org-2.jsonsrc/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/getCommitsBetween/__files/orgs_hub4j-test-org-2.json renamed to src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/getCommitsBetweenOver250/__files/orgs_hub4j-test-org-2.json src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/getCommitsBetween/__files/orgs_hub4j-test-org-2.json renamed to src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/getCommitsBetweenOver250/__files/orgs_hub4j-test-org-2.json

@@ -198,7 +198,7 @@
     "deployments_url": "https://api.github.com/repos/hub4j/github-api/deployments",
     "created_at": "2010-04-19T04:13:03Z",
     "updated_at": "2021-09-06T01:04:31Z",
-    "pushed_at": "2021-09-06T01:11:49Z",
+    "pushed_at": "2021-09-06T06:50:01Z",
     "git_url": "git://github.com/hub4j/github-api.git",
     "ssh_url": "git@github.com:hub4j/github-api.git",
     "clone_url": "https://github.com/hub4j/github-api.git",
@@ -298,7 +298,7 @@
     "deployments_url": "https://api.github.com/repos/hub4j/github-api/deployments",
     "created_at": "2010-04-19T04:13:03Z",
     "updated_at": "2021-09-06T01:04:31Z",
-    "pushed_at": "2021-09-06T01:11:49Z",
+    "pushed_at": "2021-09-06T06:50:01Z",
     "git_url": "git://github.com/hub4j/github-api.git",
     "ssh_url": "git@github.com:hub4j/github-api.git",
     "clone_url": "https://github.com/hub4j/github-api.git",