Merge pull request #795 from mockito/shipping-javadoc

New plugin for shipping Javadoc to GitHub repo

docs/faq.md

@@ -16,13 +16,28 @@ Using Gradle vocabulary: all archives produced by all subprojects in your build
 Say that one of your subprojects is a "test" or "sample" project that you don't want to publish.
 To prevent publication, disable ```bintrayUpload``` task:
 
-```java
+```groovy
 //build.gradle of a subproject that you don't want to publish
 apply plugin: 'java'
 ...
 bintrayUpload.enabled = false
 ```
 
-See [docs/getting-started.md](/docs/getting-started.md) document.
+### How to build my library against different JDK versions?
 
+Sometimes projects are build against different Java versions, but you can't release the same 
+artifact version twice. To avoid failed builds on Travis, you can configure it like that:
 
+```yaml
+matrix:
+  include:
+  - jdk: oraclejdk8
+  - jdk: oraclejdk9
+    env: SKIP_RELEASE=true
+  - jdk: openjdk10
+    env: SKIP_RELEASE=true
+  - jdk: openjdk11
+    env: SKIP_RELEASE=true
+```   
+
+Now only artifacts produced by JDK8 build will be published.

subprojects/shipkit/src/main/groovy/org/shipkit/gradle/configuration/ShipkitConfiguration.java

@@ -25,6 +25,7 @@ public class ShipkitConfiguration {
     private final ShipkitConfigurationStore store;
 
     private final GitHub gitHub = new GitHub();
+    private final Javadoc javadoc = new Javadoc();
     private final ReleaseNotes releaseNotes = new ReleaseNotes();
     private final Git git = new Git();
     private final Team team = new Team();
@@ -86,6 +87,10 @@ public GitHub getGitHub() {
         return gitHub;
     }
 
+    public Javadoc getJavadoc() {
+        return javadoc;
+    }
+
     public ReleaseNotes getReleaseNotes() {
         return releaseNotes;
     }
@@ -218,11 +223,84 @@ public String getWriteAuthToken() {
                 "  shipkit.gitHub.writeAuthToken = 'secret'");
         }
 
+        /**
+         * @see {@link #getWriteAuthToken()}
+         */
         public void setWriteAuthToken(String writeAuthToken) {
             store.put("gitHub.writeAuthToken", writeAuthToken);
         }
     }
 
+    public class Javadoc {
+        /**
+         * GitHub Javadoc repository name, for example: "mockito/shipkit-javadoc".
+         * The default value is repository with "-javadoc" suffix.
+         * @since 2.2.0
+         */
+        public String getRepository() {
+            return store.getString("javadoc.repository");
+        }
+
+        /**
+         * @see {@link #getRepository()}
+         * @since 2.2.0
+         */
+        public void setRepository(String javadocRepository) {
+            store.put("javadoc.repository", javadocRepository);
+        }
+
+        /**
+         * GitHub Javadoc repository branch name. The branch needs to exist.
+         * By default it's using the branch set as main in GitHub repo, usually master.
+         * @since 2.2.0
+         */
+        public String getRepositoryBranch() {
+            return store.getString("javadoc.repositoryBranch");
+        }
+
+        /**
+         * @see {@link #getRepositoryBranch()}
+         * @since 2.2.0
+         */
+        public void setRepositoryBranch(String javadocRepositoryBranch) {
+            store.put("javadoc.repositoryBranch", javadocRepositoryBranch);
+        }
+
+        /**
+         * GitHub Javadoc repository directory where put javadoc files. By default it's root directory.
+         * @since 2.2.0
+         */
+        public String getRepositoryDirectory() {
+            return store.getString("javadoc.repositoryDirectory");
+        }
+
+        /**
+         * @see {@link #getRepositoryDirectory()}
+         * @since 2.2.0
+         */
+        public void setRepositoryDirectory(String javadocRepositoryDirectory) {
+            store.put("javadoc.repositoryDirectory", javadocRepositoryDirectory);
+        }
+
+        /**
+         * Commit message used to commit Javadocs. Default: "Update current and ${version} Javadocs. [ci skip]"
+         * You can override this message and ${version} will be replaced by currently build version.
+         * You don't need to specify "[ci skip]" in your message - it will be added automatically.
+         * @since 2.2.0
+         */
+        public String getCommitMessage() {
+            return store.getString("javadoc.commitMessage");
+        }
+
+        /**
+         * @see {@link #getCommitMessage()}
+         * @since 2.2.0
+         */
+        public void setCommitMessage(String commitMessage) {
+            store.put("javadoc.commitMessage", commitMessage);
+        }
+    }
+
     public class ReleaseNotes {
 
         /**
@@ -303,7 +381,7 @@ public void setPublicationRepository(String publicationRepository) {
          * Get the Publication Plugin Name
          *
          * @see @setPublicationPluginName(String)
-         *
+         * @since 2.0.32
          * @deprecated since 2.1.6 because we no longer are using this one. It is scheduled to be removed in 3.0.0.
          */
         @Deprecated
@@ -328,6 +406,8 @@ public String getPublicationPluginName() {
          * </pre>
          * This will show nice badge with actual plugin version in Gradle Plugin Portal.
          *
+         * @since 2.0.32
+         *
          * @deprecated since 2.1.6 because we no longer are using this one. It is scheduled to be removed in 3.0.0.
          */
         @Deprecated

subprojects/shipkit/src/main/groovy/org/shipkit/gradle/exec/ShipkitExecTask.java

@@ -20,7 +20,7 @@ public class ShipkitExecTask extends DefaultTask {
      * Executes all commands
      */
     @TaskAction public void execCommands() {
-        new ShipkitExec().execCommands(this.getExecCommands(), this.getProject());
+        new ShipkitExec().execCommands(this.getExecCommands(), this.getProject(), null);
     }
 
     /**

subprojects/shipkit/src/main/groovy/org/shipkit/gradle/git/GitCommitTask.java

@@ -3,6 +3,7 @@
 import org.gradle.api.DefaultTask;
 import org.gradle.api.Task;
 import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.Optional;
 import org.gradle.api.tasks.SkipWhenEmpty;
 import org.gradle.api.tasks.TaskAction;
 import org.shipkit.internal.gradle.git.tasks.GitCommitImpl;
@@ -23,6 +24,7 @@ public class GitCommitTask extends DefaultTask {
     @Input String gitUserName;
     @Input String gitUserEmail;
     @Input String commitMessagePostfix;
+    @Input @Optional File workingDir;
 
     @TaskAction public void commit() {
         new GitCommitImpl().commit(this);
@@ -37,7 +39,9 @@ public class GitCommitTask extends DefaultTask {
      * @param taskMakingChange  task that makes the change, we will automatically set 'dependsOn' this task
      */
     public void addChange(List<File> files, String changeDescription, Task taskMakingChange) {
-        dependsOn(taskMakingChange);
+        if (taskMakingChange != null) {
+            dependsOn(taskMakingChange);
+        }
         filesToCommit.addAll(files);
         descriptions.add(changeDescription);
     }
@@ -92,10 +96,26 @@ public List<File> getFilesToCommit() {
     }
 
     /**
-     * Change descriptions to be included in the commit message.
+     * Get descriptions to be included in the commit message.
      * Descriptions are registered using {@link #addChange(List, String, Task)}
      */
     public List<String> getDescriptions() {
         return descriptions;
     }
+
+    /**
+     * Gets working directory where commands are executed. By default it is project root directory.
+     * @since 2.2.0
+     */
+    public File getWorkingDir() {
+        return workingDir;
+    }
+
+    /**
+     * @see {@link #getWorkingDir()}
+     * @since 2.2.0
+     */
+    public void setWorkingDir(File workingDir) {
+        this.workingDir = workingDir;
+    }
 }

subprojects/shipkit/src/main/groovy/org/shipkit/gradle/git/GitPushTask.java

@@ -2,6 +2,7 @@
 
 import org.gradle.api.DefaultTask;
 import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.Optional;
 import org.gradle.api.tasks.TaskAction;
 import org.shipkit.internal.gradle.git.tasks.GitPush;
 
@@ -20,6 +21,7 @@ public class GitPushTask extends DefaultTask {
     @Input private List<String> targets = new LinkedList<>();
     @Input private String url;
     @Input private boolean dryRun;
+    @Input @Optional private String workingDir;
     private String secretValue;
 
     @TaskAction public void gitPush() {
@@ -82,4 +84,20 @@ public String getSecretValue() {
     public void setSecretValue(String secretValue) {
         this.secretValue = secretValue;
     }
+
+    /**
+     * Gets working directory where commands are executed. By default it is project root directory.
+     * @since 2.2.0
+     */
+    public String getWorkingDir() {
+        return workingDir;
+    }
+
+    /**
+     * @see {@link #getWorkingDir()}
+     * @since 2.2.0
+     */
+    public void setWorkingDir(String workingDir) {
+        this.workingDir = workingDir;
+    }
 }

subprojects/shipkit/src/main/groovy/org/shipkit/internal/gradle/exec/ShipkitExec.java

@@ -10,13 +10,20 @@
 import org.shipkit.internal.exec.ExternalProcessStream;
 import org.shipkit.internal.gradle.util.StringUtil;
 
+import java.io.File;
 import java.util.Collection;
 
 public class ShipkitExec {
 
     private final static Logger LOG = Logging.getLogger(ShipkitExec.class);
 
-    public void execCommands(Collection<ExecCommand> execCommands, Project project) {
+    /**
+     * Execute commands and print execution summary.
+     * @param execCommands  Commands to execute
+     * @param project       Gradle Project instance
+     * @param workingDir    Working directory where command will be executed, it may be null
+     */
+    public void execCommands(Collection<ExecCommand> execCommands, Project project, File workingDir) {
         for (final ExecCommand execCommand : execCommands) {
             ExecResult result = project.exec(new Action<ExecSpec>() {
                 @Override
@@ -25,6 +32,9 @@ public void execute(ExecSpec spec) {
                     spec.commandLine(execCommand.getCommandLine());
                     spec.setStandardOutput(new ExternalProcessStream(execCommand.getLoggingPrefix(), System.out));
                     spec.setErrorOutput(new ExternalProcessStream(execCommand.getLoggingPrefix(), System.err));
+                    if (workingDir != null) {
+                        spec.setWorkingDir(workingDir);
+                    }
 
                     execCommand.getSetupAction().execute(spec);
 

subprojects/shipkit/src/main/groovy/org/shipkit/internal/gradle/git/GitCommitTaskFactory.java

@@ -0,0 +1,21 @@
+package org.shipkit.internal.gradle.git;
+
+import org.gradle.api.Project;
+import org.shipkit.gradle.configuration.ShipkitConfiguration;
+import org.shipkit.gradle.git.GitCommitTask;
+import org.shipkit.internal.gradle.configuration.ShipkitConfigurationPlugin;
+import org.shipkit.internal.gradle.util.TaskMaker;
+
+public class GitCommitTaskFactory {
+
+    public static GitCommitTask createGitCommitTask(Project project, String taskName, String description) {
+        ShipkitConfiguration conf = project.getPlugins().apply(ShipkitConfigurationPlugin.class).getConfiguration();
+
+        return TaskMaker.task(project, taskName, GitCommitTask.class, task -> {
+            task.setDescription(description);
+            task.setGitUserName(conf.getGit().getUser());
+            task.setGitUserEmail(conf.getGit().getEmail());
+            task.setCommitMessagePostfix(conf.getGit().getCommitMessagePostfix());
+        });
+    }
+}

subprojects/shipkit/src/main/groovy/org/shipkit/internal/gradle/git/GitPlugin.java

@@ -54,14 +54,8 @@ public class GitPlugin implements Plugin<Project> {
     public void apply(final Project project) {
         final ShipkitConfiguration conf = project.getPlugins().apply(ShipkitConfigurationPlugin.class).getConfiguration();
 
-        TaskMaker.task(project, GIT_COMMIT_TASK, GitCommitTask.class, new Action<GitCommitTask>() {
-            public void execute(final GitCommitTask t) {
-                t.setDescription("Commits all changed files using generic --author and aggregated commit message");
-                t.setGitUserName(conf.getGit().getUser());
-                t.setGitUserEmail(conf.getGit().getEmail());
-                t.setCommitMessagePostfix(conf.getGit().getCommitMessagePostfix());
-            }
-        });
+        GitCommitTaskFactory.createGitCommitTask(project, GIT_COMMIT_TASK,
+            "Commits all changed files using generic --author and aggregated commit message");
 
         TaskMaker.task(project, GIT_TAG_TASK, ShipkitExecTask.class, new Action<ShipkitExecTask>() {
             public void execute(final ShipkitExecTask t) {
@@ -82,7 +76,7 @@ public void execute(final GitPushTask t) {
                 t.getTargets().add(GitUtil.getTag(conf, project));
                 t.setDryRun(conf.isDryRun());
 
-                GitUrlInfo info = new GitUrlInfo(conf);
+                GitUrlInfo info = new GitUrlInfo(conf, conf.getGitHub().getRepository());
                 t.setUrl(info.getGitUrl());
                 t.setSecretValue(info.getWriteToken());
 

subprojects/shipkit/src/main/groovy/org/shipkit/internal/gradle/git/GitUrlInfo.java

@@ -9,8 +9,8 @@ public class GitUrlInfo {
     private final String gitUrl;
     private final String writeToken;
 
-    public GitUrlInfo(ShipkitConfiguration conf) {
-        gitUrl = getGitHubUrl(conf.getGitHub().getRepository(), conf);
+    public GitUrlInfo(ShipkitConfiguration conf, String repository) {
+        gitUrl = getGitHubUrl(repository, conf);
         writeToken = conf.getLenient().getGitHub().getWriteAuthToken();
     }