Skip to content

Commit

Permalink
Add beta api annotation to project
Browse files Browse the repository at this point in the history
  • Loading branch information
marcoferrer committed Dec 16, 2020
1 parent e3e495b commit 4e7ac70
Show file tree
Hide file tree
Showing 13 changed files with 90 additions and 25 deletions.
6 changes: 3 additions & 3 deletions src/main/java/org/kohsuke/github/AbstractBuilder.java
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ protected AbstractBuilder(@Nonnull Class<R> finalReturnType,
* if there is an I/O Exception
*/
@Nonnull
@Preview
@BetaApi
@Deprecated
public R done() throws IOException {
R result;
Expand Down Expand Up @@ -127,7 +127,7 @@ public R done() throws IOException {
* if an I/O error occurs
*/
@Nonnull
@Preview
@BetaApi
@Deprecated
protected S with(@Nonnull String name, Object value) throws IOException {
requester.with(name, value);
Expand All @@ -148,7 +148,7 @@ protected S with(@Nonnull String name, Object value) throws IOException {
* if an I/O error occurs
*/
@Nonnull
@Preview
@BetaApi
@Deprecated
protected S continueOrDone() throws IOException {
// This little bit of roughness in this base class means all inheriting builders get to create Updater and
Expand Down
18 changes: 18 additions & 0 deletions src/main/java/org/kohsuke/github/BetaApi.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
package org.kohsuke.github;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
* Indicates that the method/class/etc marked is a beta implementation of an sdk feature.
* <p>
* These APIs are subject to change and not a part of the backward compatibility commitment. Always used in conjunction
* with 'deprecated' to raise awareness to clients.
* </p>
*
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface BetaApi {
}
8 changes: 4 additions & 4 deletions src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ public class GHAppCreateTokenBuilder {
protected final Requester builder;
private final String apiUrlTail;

@Preview
@BetaApi
@Deprecated
GHAppCreateTokenBuilder(GitHub root, String apiUrlTail) {
this.root = root;
this.apiUrlTail = apiUrlTail;
this.builder = root.createRequest();
}

@Preview
@BetaApi
@Deprecated
GHAppCreateTokenBuilder(GitHub root, String apiUrlTail, Map<String, GHPermissionType> permissions) {
this(root, apiUrlTail);
Expand All @@ -43,7 +43,7 @@ public class GHAppCreateTokenBuilder {
* Array containing the repositories Ids
* @return a GHAppCreateTokenBuilder
*/
@Preview
@BetaApi
@Deprecated
public GHAppCreateTokenBuilder repositoryIds(List<Long> repositoryIds) {
this.builder.with("repository_ids", repositoryIds);
Expand All @@ -58,7 +58,7 @@ public GHAppCreateTokenBuilder repositoryIds(List<Long> repositoryIds) {
* Map containing the permission names and types.
* @return a GHAppCreateTokenBuilder
*/
@Preview
@BetaApi
@Deprecated
public GHAppCreateTokenBuilder permissions(Map<String, GHPermissionType> permissions) {
Map<String, String> retMap = new HashMap<>();
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/org/kohsuke/github/GHAppInstallation.java
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@ public void deleteInstallation() throws IOException {
* @return a GHAppCreateTokenBuilder instance
* @deprecated Use {@link GHAppInstallation#createToken()} instead.
*/
@Preview
@BetaApi
@Deprecated
public GHAppCreateTokenBuilder createToken(Map<String, GHPermissionType> permissions) {
return new GHAppCreateTokenBuilder(root,
Expand All @@ -361,7 +361,7 @@ public GHAppCreateTokenBuilder createToken(Map<String, GHPermissionType> permiss
*
* @return a GHAppCreateTokenBuilder instance
*/
@Preview
@BetaApi
@Deprecated
public GHAppCreateTokenBuilder createToken() {
return new GHAppCreateTokenBuilder(root, String.format("/app/installations/%d/access_tokens", getId()));
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/org/kohsuke/github/GHBranch.java
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ public String getName() {
*
* @return true if the push to this branch is restricted via branch protection.
*/
@Preview
@Preview(Previews.LUKE_CAGE)
@Deprecated
public boolean isProtected() {
return protection;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/org/kohsuke/github/GHCommitComment.java
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ public void update(String body) throws IOException {
this.body = body;
}

@Preview
@Preview(SQUIRREL_GIRL)
@Deprecated
public GHReaction createReaction(ReactionContent content) throws IOException {
return owner.root.createRequest()
Expand Down
12 changes: 6 additions & 6 deletions src/main/java/org/kohsuke/github/GHLabel.java
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ static Collection<String> toNames(Collection<GHLabel> labels) {
* @throws IOException
* the io exception
*/
@Preview
@BetaApi
@Deprecated
static Creator create(GHRepository repository) throws IOException {
return new Creator(repository);
Expand Down Expand Up @@ -179,7 +179,7 @@ static PagedIterable<GHLabel> readAll(@Nonnull final GHRepository repository) th
*
* @return a {@link Updater}
*/
@Preview
@BetaApi
@Deprecated
public Updater update() {
return new Updater(this);
Expand All @@ -190,7 +190,7 @@ public Updater update() {
*
* @return a {@link Setter}
*/
@Preview
@BetaApi
@Deprecated
public Setter set() {
return new Setter(this);
Expand Down Expand Up @@ -227,7 +227,7 @@ public int hashCode() {
*
* {@link #done()} is called automatically after the property is set.
*/
@Preview
@BetaApi
@Deprecated
public static class Setter extends GHLabelBuilder<GHLabel> {
private Setter(@Nonnull GHLabel base) {
Expand All @@ -241,7 +241,7 @@ private Setter(@Nonnull GHLabel base) {
*
* Consumer must call {@link #done()} to commit changes.
*/
@Preview
@BetaApi
@Deprecated
public static class Updater extends GHLabelBuilder<Updater> {
private Updater(@Nonnull GHLabel base) {
Expand All @@ -255,7 +255,7 @@ private Updater(@Nonnull GHLabel base) {
*
* Consumer must call {@link #done()} to create the new instance.
*/
@Preview
@BetaApi
@Deprecated
public static class Creator extends GHLabelBuilder<Creator> {
private Creator(@Nonnull GHRepository repository) {
Expand Down
6 changes: 3 additions & 3 deletions src/main/java/org/kohsuke/github/GHLabelBuilder.java
Original file line number Diff line number Diff line change
Expand Up @@ -38,21 +38,21 @@ protected GHLabelBuilder(@Nonnull Class<S> intermediateReturnType,
}

@Nonnull
@Preview
@BetaApi
@Deprecated
public S name(String value) throws IOException {
return with("name", value);
}

@Nonnull
@Preview
@BetaApi
@Deprecated
public S color(String value) throws IOException {
return with("color", value);
}

@Nonnull
@Preview
@BetaApi
@Deprecated
public S description(String value) throws IOException {
return with("description", value);
Expand Down
1 change: 0 additions & 1 deletion src/main/java/org/kohsuke/github/GHRelease.java
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,6 @@ public GHAsset uploadAsset(String filename, InputStream stream, String contentTy
* existing logic in place for backwards compatibility.
*/
@Deprecated
@Preview
public List<GHAsset> assets() {
return assets;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ public PagedIterable<ContributorStats> getContributorStats() throws IOException,
* @throws InterruptedException
* the interrupted exception
*/
@Preview
@BetaApi
@Deprecated
@SuppressWarnings("SleepWhileInLoop")
@SuppressFBWarnings(value = { "RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE" }, justification = "JSON API")
Expand Down
2 changes: 0 additions & 2 deletions src/main/java/org/kohsuke/github/GitUser.java
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,6 @@ public String getEmail() {
*
* @return GitHub username
*/
@Preview
@Deprecated
@CheckForNull
public String getUsername() {
return username;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/org/kohsuke/github/Preview.java
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,6 @@
*
* @return The API preview media type.
*/
public Previews[] value() default {};
public Previews[] value();

}
50 changes: 50 additions & 0 deletions src/test/java/org/kohsuke/github/ArchTests.java
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
package org.kohsuke.github;

import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaAnnotation;
import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.BeforeClass;
import org.junit.Test;

import static com.tngtech.archunit.lang.conditions.ArchConditions.beAnnotatedWith;
import static com.tngtech.archunit.lang.conditions.ArchConditions.not;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.fields;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.methods;
Expand All @@ -19,6 +23,17 @@ public class ArchTests {
.withImportOption(new ImportOption.DoNotIncludeJars())
.importPackages("org.kohsuke.github");

private static final DescribedPredicate<JavaAnnotation<?>> previewAnnotationWithNoMediaType = new DescribedPredicate<JavaAnnotation<?>>(
"preview has no required media types defined") {

@Override
public boolean apply(JavaAnnotation<?> javaAnnotation) {
boolean isPreview = javaAnnotation.getRawType().isEquivalentTo(Preview.class);
Object[] values = (Object[]) javaAnnotation.getProperties().get("value");
return isPreview && values != null && values.length < 1;
}
};

@BeforeClass
public static void beforeClass() {
assertTrue(classFiles.size() > 0);
Expand All @@ -33,12 +48,14 @@ public void testPreviewsAreFlaggedAsDeprecated() {
.areAnnotatedWith(Preview.class)
.should()
.beAnnotatedWith(Deprecated.class)
.andShould(not(beAnnotatedWith(previewAnnotationWithNoMediaType)))
.because(reason);

ArchRule methodRule = methods().that()
.areAnnotatedWith(Preview.class)
.should()
.beAnnotatedWith(Deprecated.class)
.andShould(not(beAnnotatedWith(previewAnnotationWithNoMediaType)))
.because(reason);

ArchRule enumFieldsRule = fields().that()
Expand All @@ -48,6 +65,39 @@ public void testPreviewsAreFlaggedAsDeprecated() {
.areAnnotatedWith(Preview.class)
.should()
.beAnnotatedWith(Deprecated.class)
.andShould(not(beAnnotatedWith(previewAnnotationWithNoMediaType)))
.because(reason);

classRule.check(classFiles);
enumFieldsRule.check(classFiles);
methodRule.check(classFiles);

}

@Test
public void testBetaApisAreFlaggedAsDeprecated() {

String reason = "all beta APIs must be annotated as @Deprecated until they are promoted to stable";

ArchRule classRule = classes().that()
.areAnnotatedWith(BetaApi.class)
.should()
.beAnnotatedWith(Deprecated.class)
.because(reason);

ArchRule methodRule = methods().that()
.areAnnotatedWith(BetaApi.class)
.should()
.beAnnotatedWith(Deprecated.class)
.because(reason);

ArchRule enumFieldsRule = fields().that()
.areDeclaredInClassesThat()
.areEnums()
.and()
.areAnnotatedWith(BetaApi.class)
.should()
.beAnnotatedWith(Deprecated.class)
.because(reason);

classRule.check(classFiles);
Expand Down

0 comments on commit 4e7ac70

Please sign in to comment.