Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 1994f47

Browse filesBrowse files
bitwisemanbitwiseman
committed
More javadoc and query validation
Added javadoc for each value of Fork search mode enum. Made passing UNKNOWN to visibility() throw a GHException. UNKNOWN a placeholder and should never be passed into any method in the API.
1 parent a69bff3 commit 1994f47
Copy full SHA for 1994f47

File tree

Expand file treeCollapse file tree

3 files changed

+61
-23
lines changed
Filter options
Expand file treeCollapse file tree

3 files changed

+61
-23
lines changed

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

Copy file name to clipboardExpand all lines: src/main/java/org/kohsuke/github/GHRepository.java
+14-1Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -727,7 +727,20 @@ public boolean isPrivate() {
727727
* Visibility of a repository.
728728
*/
729729
public enum Visibility {
730-
PUBLIC, INTERNAL, PRIVATE, UNKNOWN;
730+
PUBLIC,
731+
INTERNAL,
732+
PRIVATE,
733+
734+
/**
735+
* Placeholder for unexpected data values.
736+
*
737+
* This avoids throwing exceptions during data binding or reading when the list of allowed values returned from
738+
* GitHub is expanded.
739+
*
740+
* Do not pass this value to any methods. If this value is returned during a request, check the log output and
741+
* report an issue for the missing value.
742+
*/
743+
UNKNOWN;
731744

732745
public static Visibility from(String value) {
733746
return EnumUtils.getNullableEnumOrDefault(Visibility.class, value, Visibility.UNKNOWN);

‎src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java

Copy file name to clipboardExpand all lines: src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java
+38-17Lines changed: 38 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,16 @@ public GHRepositorySearchBuilder forks(String v) {
5555
/**
5656
* Searching in forks
5757
*
58-
* By default, forks are not shown in search results. Forks are only indexed for code search when they have more
59-
* stars than the parent repository. You will not be able to search the code in a fork that has less stars than its
60-
* parent. To show forks with more stars than the parent repository in code search results, add
61-
* Fork.ALL_INCLUDING_FORKS or Fork.FORKS_ONLY.
58+
* The default search mode is {@link Fork#PARENT_ONLY}. In that mode, forks are not included in search results.
59+
*
60+
* <p>
61+
* Passing {@link Fork#PARENT_AND_FORKS} or {@link Fork#FORKS_ONLY} will show results from forks, but only if they
62+
* have more stars than the parent repository.
63+
*
64+
* <p>
65+
* IMPORTANT: Regardless of this setting, no search results will ever be returned for forks with equal or fewer
66+
* stars than the parent repository. Forks with less stars than the parent repository are not included in the index
67+
* for code searching.
6268
*
6369
* @param fork
6470
* search mode for forks
@@ -71,7 +77,7 @@ public GHRepositorySearchBuilder forks(String v) {
7177
*
7278
*/
7379
public GHRepositorySearchBuilder fork(Fork fork) {
74-
if (fork == Fork.DEFAULT) {
80+
if (Fork.PARENT_ONLY.equals(fork)) {
7581
this.terms.removeIf(term -> term.contains("fork:"));
7682
return this;
7783
}
@@ -82,21 +88,21 @@ public GHRepositorySearchBuilder fork(Fork fork) {
8288
/**
8389
* Search by repository visibility
8490
*
85-
* If visibility param value equals to GHRepository.Visibility.UNKNOWN, this search criteria will be ignored.
86-
*
8791
* @param visibility
8892
* repository visibility
8993
*
9094
* @return the gh repository search builder
91-
*
95+
* @throws GHException
96+
* if {@link GHRepository.Visibility#UNKNOWN} is passed. UNKNOWN is a placeholder for unexpected values
97+
* encountered when reading data.
9298
* @see <a href=
9399
* "https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-for-repositories#search-by-repository-visibility">Search
94100
* by repository visibility</a>
95-
*
96101
*/
97102
public GHRepositorySearchBuilder visibility(GHRepository.Visibility visibility) {
98103
if (visibility == GHRepository.Visibility.UNKNOWN) {
99-
return this;
104+
throw new GHException(
105+
"UNKNOWN is a placeholder for unexpected values encountered when reading data. It cannot be passed as a search parameter.");
100106
}
101107

102108
return q("is:" + visibility);
@@ -211,15 +217,30 @@ public enum Sort {
211217
}
212218

213219
/**
214-
* The enum Fork.
215-
*
216-
* By default, forks are not shown in search results. Forks are only indexed for code search when they have more
217-
* stars than the parent repository. You will not be able to search the code in a fork that has less stars than its
218-
* parent. To show forks with more stars than the parent repository in code search results, add
219-
* Fork.ALL_INCLUDING_FORKS or Fork.FORKS_ONLY.
220+
* The enum for Fork search mode
220221
*/
221222
public enum Fork {
222-
ALL_INCLUDING_FORKS("true"), FORKS_ONLY("only"), DEFAULT("ignore");
223+
224+
/**
225+
* Search in the parent repository and in forks with more stars than the parent repository.
226+
*
227+
* Forks with the same or fewer stars than the parent repository are still ignored.
228+
*/
229+
PARENT_AND_FORKS("true"),
230+
231+
/**
232+
* Search only in forks with more stars than the parent repository.
233+
*
234+
* The parent repository is ignored. If no forks have more stars than the parent, no results will be returned.
235+
*/
236+
FORKS_ONLY("only"),
237+
238+
/**
239+
* (Default) Search only the parent repository.
240+
*
241+
* Forks are ignored.
242+
*/
243+
PARENT_ONLY("");
223244

224245
private String filterMode;
225246
Fork(String mode) {

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

Copy file name to clipboardExpand all lines: src/test/java/org/kohsuke/github/GHRepositoryTest.java
+9-5Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
import static org.hamcrest.Matchers.*;
2222
import static org.hamcrest.core.IsInstanceOf.instanceOf;
23+
import static org.junit.Assert.assertThrows;
2324
import static org.kohsuke.github.GHVerification.Reason.*;
2425

2526
/**
@@ -422,7 +423,7 @@ public void searchAllPublicAndForkedRepos() throws IOException {
422423
PagedSearchIterable<GHRepository> list = gitHub.searchRepositories()
423424
.user("t0m4uk1991")
424425
.visibility(GHRepository.Visibility.PUBLIC)
425-
.fork(GHRepositorySearchBuilder.Fork.ALL_INCLUDING_FORKS)
426+
.fork(GHRepositorySearchBuilder.Fork.PARENT_AND_FORKS)
426427
.list();
427428
List<GHRepository> u = list.toList();
428429
assertThat(u.size(), is(14));
@@ -446,8 +447,11 @@ public void searchForPublicForkedOnlyRepos() throws IOException {
446447
@Test
447448
public void ghRepositorySearchBuilderIgnoresUnknownVisibility() {
448449
GHRepositorySearchBuilder ghRepositorySearchBuilder;
449-
ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub).visibility(Visibility.UNKNOWN);
450-
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("is:")).count(), is(0L));
450+
451+
GHException exception = assertThrows(GHException.class,
452+
() -> new GHRepositorySearchBuilder(gitHub).visibility(Visibility.UNKNOWN));
453+
assertThat(exception.getMessage(),
454+
startsWith("UNKNOWN is a placeholder for unexpected values encountered when reading data."));
451455

452456
ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub).visibility(Visibility.PUBLIC);
453457
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("is:")).count(), is(1L));
@@ -462,15 +466,15 @@ public void ghRepositorySearchBuilderIgnoresUnknownVisibility() {
462466
@Test
463467
public void ghRepositorySearchBuilderForkDefaultResetForksSearchTerms() {
464468
GHRepositorySearchBuilder ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub);
465-
ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.ALL_INCLUDING_FORKS);
469+
ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.PARENT_AND_FORKS);
466470
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:true")).count(), is(1L));
467471
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(1L));
468472

469473
ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.FORKS_ONLY);
470474
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:only")).count(), is(1L));
471475
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(2L));
472476

473-
ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.DEFAULT);
477+
ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.PARENT_ONLY);
474478
assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(0L));
475479
}
476480

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.