Merge remote-tracking branch 'upstream/master' into bugfix-883

Author: bitwiseman

CONTRIBUTING.md

@@ -14,6 +14,10 @@ Example:
 
 This the default behavior.
 
+Example for a single test case:
+
+`mvn install -Dtest=WireMockStatusReporterTest#user_whenProxying_AuthCorrectlyConfigured`
+
 
 ### Setting up credential
 
@@ -27,21 +31,37 @@ This the default behavior.
 
     `WireMockStatusReporterTest: GitHub proxying and user auth correctly configured for user login: <your login>`
 
-Whenever you run tests with `-Dtest.github.useProxy`, they will try to get data from local files but will fallback to proxying to github if not found.
-
+Whenever you run tests with `-Dtest.github.useProxy`, they will try to get data from local files but will fallback to proxying to GitHub if not found.
 
 ### Writing a new test
 
 Once you have credentials setup, you add new test classes and test methods as you would normally.
-Keep `useProxy` enabled and iterate on your tests as needed. Remember, while proxying your tests are interacting with GitHub - you will need to clean up your state between runs.
 
-When you are ready to create a snapshot of your test data,
-run your test with `test.github.takeSnapshot` ("-Dtest.github.takeSnapshot" as a Java VM option).  For example:
+#### Running tests using GitHub test proxy
+
+Keep `useProxy` enabled and iterate on your tests as needed. With `useProxy` enabled your tests will interact with 
+GitHub - you will need to clean up your server-state between runs. This can be done manually to start with.
+Once your test code is somewhat stable, use `getGitHubBeforeAfter()` to get a `GitHub` instance for test setup and cleanup.
+Interactions with that `GitHub` instance will not be recorded as part of the test, keeping the test data files to a minimum. 
+
+#### Running tests against your personal GitHub user account
+
+By default, test helper methods such as `getTempRepository()` target the `hub4j-test-org` GitHub organization.
+Please request access to this org to record your tests before submitting a PR.  This helps keep the project stable and nimble.
+Until you have access (or if you don't want access), you can set the following additional system property to target 
+your personal github account.
+
+    `mvn install -Dtest.github.org=false -Dtest=YourTestClassName`
+
+#### Taking a snapshot 
+
+When you are ready to create a snapshot of your test data, run your test with `test.github.takeSnapshot`  ("-Dtest.github.takeSnapshot" as 
+a Java VM option). For example:
 
-    `mvn install -Dtest.github.takeSnapshot -Dtest=YourTestClassName`
+    `mvn install -Dtest.github.takeSnapshot -Dtest.github.org=false -Dtest=YourTestClassName`
 
-The above command would create snapshot WireMock data files under the path `src/test/resources/org/kohsuhke/github/YourTestClassName/wiremock`.
-Each method would get a separate director that would hold the data files for that test method.
+The above command will create snapshot WireMock data files under the path `src/test/resources/org/kohsuhke/github/YourTestClassName/wiremock`.
+Each method will get a separate directory that will hold the data files for that test method.
 
 Add all files including the generated data to your commit and submit a PR.
 

pom.xml

@@ -33,14 +33,13 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <spotbugs-maven-plugin.version>4.0.4</spotbugs-maven-plugin.version>
-    <spotbugs.version>4.1.2</spotbugs.version>
+    <spotbugs-maven-plugin.version>4.1.4</spotbugs-maven-plugin.version>
+    <spotbugs.version>4.1.3</spotbugs.version>
     <spotbugs-maven-plugin.failOnError>true</spotbugs-maven-plugin.failOnError>
     <hamcrest.version>2.2</hamcrest.version>
     <okhttp3.version>4.4.1</okhttp3.version>
     <okio.version>2.5.0</okio.version>
-    <formatter-maven-plugin.goal>format</formatter-maven-plugin.goal>
-    <impsort-maven-plugin.goal>sort</impsort-maven-plugin.goal>
+    <spotless-maven-plugin.goal>apply</spotless-maven-plugin.goal>
     <!-- Using this as the minimum bar for code coverage.  Adding methods without covering them will fail this. -->
     <jacoco.coverage.target.bundle.method>0.60</jacoco.coverage.target.bundle.method>
     <jacoco.coverage.target.class.method>0.25</jacoco.coverage.target.class.method>
@@ -261,7 +260,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-project-info-reports-plugin</artifactId>
-        <version>3.1.0</version>
+        <version>3.1.1</version>
         <dependencies>
           <dependency>
             <groupId>org.apache.bcel</groupId>
@@ -343,37 +342,34 @@
         </executions>
       </plugin>
       <plugin>
-        <groupId>net.revelc.code.formatter</groupId>
-        <artifactId>formatter-maven-plugin</artifactId>
-        <version>2.12.1</version>
+        <groupId>com.diffplug.spotless</groupId>
+        <artifactId>spotless-maven-plugin</artifactId>
+        <version>2.6.1</version>
         <executions>
           <execution>
+            <id>spotless-check</id>
+            <phase>process-sources</phase>
             <goals>
-              <goal>${formatter-maven-plugin.goal}</goal>
+              <goal>${spotless-maven-plugin.goal}</goal>
             </goals>
-            <configuration>
-              <configFile>src/main/resources/eclipse/formatter.xml</configFile>
-              <cachedir>${project.build.directory}/.cache</cachedir>
-            </configuration>
           </execution>
         </executions>
-      </plugin>
-      <plugin>
-        <groupId>net.revelc.code</groupId>
-        <artifactId>impsort-maven-plugin</artifactId>
-        <version>1.4.1</version>
         <configuration>
-          <groups>*,java.,javax.</groups>
-          <removeUnused>true</removeUnused>
-          <staticAfter>true</staticAfter>
+          <java>
+            <eclipse>
+              <file>${basedir}/src/build/eclipse/formatter.xml</file>
+            </eclipse>
+
+            <importOrder>
+              <file>${basedir}/src/build/eclipse/eclipse.importorder</file>
+            </importOrder>
+            <removeUnusedImports />
+
+            <trimTrailingWhitespace />
+            <endWithNewline />
+
+          </java>
         </configuration>
-        <executions>
-          <execution>
-            <goals>
-              <goal>${impsort-maven-plugin.goal}</goal>
-            </goals>
-          </execution>
-        </executions>
       </plugin>
       <plugin>
         <groupId>com.github.spotbugs</groupId>
@@ -410,6 +406,12 @@
       <artifactId>commons-lang3</artifactId>
       <version>3.9</version>
     </dependency>
+    <dependency>
+      <groupId>com.tngtech.archunit</groupId>
+      <artifactId>archunit</artifactId>
+      <version>0.15.0</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>org.hamcrest</groupId>
       <artifactId>hamcrest</artifactId>
@@ -481,7 +483,7 @@
     <dependency>
       <groupId>org.eclipse.jgit</groupId>
       <artifactId>org.eclipse.jgit</artifactId>
-      <version>5.9.0.202009080501-r</version>
+      <version>5.10.0.202012080955-r</version>
       <scope>test</scope>
     </dependency>
     <dependency>
@@ -561,7 +563,7 @@
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-simple</artifactId>
-      <version>1.7.2</version>
+      <version>1.7.30</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
@@ -589,8 +591,7 @@
         </os>
       </activation>
       <properties>
-        <formatter-maven-plugin.goal>validate</formatter-maven-plugin.goal>
-        <impsort-maven-plugin.goal>check</impsort-maven-plugin.goal>
+        <spotless-maven-plugin.goal>check</spotless-maven-plugin.goal>
       </properties>
     </profile>
     <profile>
@@ -615,8 +616,7 @@
     <profile>
       <id>release</id>
       <properties>
-        <formatter-maven-plugin.goal>validate</formatter-maven-plugin.goal>
-        <impsort-maven-plugin.goal>check</impsort-maven-plugin.goal>
+        <spotless-maven-plugin.goal>check</spotless-maven-plugin.goal>
       </properties>
       <build>
         <plugins>

src/build/eclipse/eclipse.importorder

@@ -0,0 +1,6 @@
+#Organize Import Order
+# Import this file in Window -> Preferences -> Java -> Code Style -> Organize Imports -> Import...
+0=
+1=java
+2=javax
+3=\#

src/main/resources/eclipse/formatter.xml renamed to src/build/eclipse/formatter.xml

@@ -12,14 +12,14 @@
  * <p>
  * Batching looks like this:
  * </p>
- * 
+ *
  * <pre>
  * update().someName(value).otherName(value).done()
  * </pre>
  * <p>
  * Single changes look like this:
  * </p>
- * 
+ *
  * <pre>
  * set().someName(value);
  * set().otherName(value);
@@ -38,7 +38,7 @@
  *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@link S}
  *            the same as {@link R}, this builder will commit changes after each call to {@link #with(String, Object)}.
  */
-abstract class AbstractBuilder<R, S> {
+abstract class AbstractBuilder<R, S> extends GitHubInteractiveObject {
 
     @Nonnull
     private final Class<R> returnType;
@@ -75,6 +75,7 @@ protected AbstractBuilder(@Nonnull Class<R> finalReturnType,
             @Nonnull Class<S> intermediateReturnType,
             @Nonnull GitHub root,
             @CheckForNull R baseInstance) {
+        super(root);
         this.requester = root.createRequest();
         this.returnType = finalReturnType;
         this.commitChangesImmediately = returnType.equals(intermediateReturnType);
@@ -97,7 +98,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 +128,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 +149,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/AbstractBuilder.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/BetaApi.java

@@ -15,7 +15,6 @@
  */
 public class GHApp extends GHObject {
 
-    private GitHub root;
     private GHUser owner;
     private String name;
     private String description;
@@ -189,7 +188,7 @@ GHApp wrapUp(GitHub root) {
      * @return a list of App installations
      * @see <a href="https://developer.github.com/v3/apps/#list-installations">List installations</a>
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public PagedIterable<GHAppInstallation> listInstallations() {
         return root.createRequest()
@@ -210,7 +209,7 @@ public PagedIterable<GHAppInstallation> listInstallations() {
      *             on error
      * @see <a href="https://developer.github.com/v3/apps/#get-an-installation">Get an installation</a>
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public GHAppInstallation getInstallationById(long id) throws IOException {
         return root.createRequest()
@@ -233,7 +232,7 @@ public GHAppInstallation getInstallationById(long id) throws IOException {
      * @see <a href="https://developer.github.com/v3/apps/#get-an-organization-installation">Get an organization
      *      installation</a>
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public GHAppInstallation getInstallationByOrganization(String name) throws IOException {
         return root.createRequest()
@@ -258,7 +257,7 @@ public GHAppInstallation getInstallationByOrganization(String name) throws IOExc
      * @see <a href="https://developer.github.com/v3/apps/#get-a-repository-installation">Get a repository
      *      installation</a>
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public GHAppInstallation getInstallationByRepository(String ownerName, String repositoryName) throws IOException {
         return root.createRequest()
@@ -280,7 +279,7 @@ public GHAppInstallation getInstallationByRepository(String ownerName, String re
      *             on error
      * @see <a href="https://developer.github.com/v3/apps/#get-a-user-installation">Get a user installation</a>
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public GHAppInstallation getInstallationByUser(String name) throws IOException {
         return root.createRequest()

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

@@ -14,20 +14,19 @@
  * @see GHAppInstallation#createToken(Map) GHAppInstallation#createToken(Map)
  * @see GHAppInstallation#createToken() GHAppInstallation#createToken()
  */
-public class GHAppCreateTokenBuilder {
-    private final GitHub root;
+public class GHAppCreateTokenBuilder extends GitHubInteractiveObject {
     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 +42,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 +57,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<>();
@@ -78,7 +77,7 @@ public GHAppCreateTokenBuilder permissions(Map<String, GHPermissionType> permiss
      * @throws IOException
      *             on error
      */
-    @Preview
+    @Preview(MACHINE_MAN)
     @Deprecated
     public GHAppInstallationToken create() throws IOException {
         return builder.method("POST")