Merge pull request #1002 from marcoferrer/add-sdk-beta-annotation

Implement BetaApi annotation for hub4j sdk

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

@@ -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;
@@ -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);
@@ -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

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

@@ -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 {
+}

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

@@ -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);
@@ -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);
@@ -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<>();

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

@@ -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,
@@ -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()));

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

@@ -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;

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

@@ -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()

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

@@ -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);
@@ -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);
@@ -190,7 +190,7 @@ public Updater update() {
      * 
      * @return a {@link Setter}
      */
-    @Preview
+    @BetaApi
     @Deprecated
     public Setter set() {
         return new Setter(this);
@@ -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) {
@@ -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) {
@@ -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) {

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

@@ -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);

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

@@ -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;
     }

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

@@ -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")

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

@@ -42,8 +42,6 @@ public String getEmail() {
      *
      * @return GitHub username
      */
-    @Preview
-    @Deprecated
     @CheckForNull
     public String getUsername() {
         return username;

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

@@ -25,6 +25,6 @@
      *
      * @return The API preview media type.
      */
-    public Previews[] value() default {};
+    public Previews[] value();
 
 }

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

@@ -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;
@@ -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);
@@ -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()
@@ -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);