Repository: commons-release-plugin Updated Branches: refs/heads/master 9a2db79a9 -> 7b1b50f4b
COMMONSSITE-97: More documentation Project: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/commit/7b1b50f4 Tree: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/tree/7b1b50f4 Diff: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/diff/7b1b50f4 Branch: refs/heads/master Commit: 7b1b50f4b0eaadebcb46cdcd2c79ac042e50845f Parents: 9a2db79 Author: Rob Tompkins <chtom...@gmail.com> Authored: Tue Jan 9 10:20:36 2018 -0500 Committer: Rob Tompkins <chtom...@gmail.com> Committed: Tue Jan 9 10:20:36 2018 -0500 ---------------------------------------------------------------------- README.md | 2 +- pom.xml | 44 +++++++++++ .../mojos/CommonsDistributionStagingMojo.java | 80 ++++++++++++++++++-- src/site/xdoc/index.xml | 8 +- 4 files changed, 125 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/7b1b50f4/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index c8475ce..a72e239 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ More information can be found on the [homepage](https://commons.apache.org/prope The [JavaDoc](https://commons.apache.org/proper/commons-commons-release-plugin/javadocs/api-release) can be browsed. Questions related to the usage of Apache Commons Release Plugin should be posted to the [user mailing list][ml]. -[](https://travis-ci.org/apache/commons-release-plugin) +[](https://travis-ci.org/apache/commons-release-plugin) [](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-release-plugin) Where can I get the latest release? http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/7b1b50f4/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 1422c8d..4db7458 100644 --- a/pom.xml +++ b/pom.xml @@ -197,6 +197,28 @@ </pluginManagement> <plugins> <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>${commons.javadoc.version}</version> + <configuration> + <!-- keep only errors and warnings --> + <show>private</show> + <quiet>true</quiet> + <encoding>${commons.encoding}</encoding> + <notimestamp>true</notimestamp> + <links> + <link>${commons.javadoc.java.link}</link> + <link>${commons.javadoc.javaee.link}</link> + </links> + <archive> + <manifest> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries> + </manifest> + </archive> + </configuration> + </plugin> + <plugin> <artifactId>maven-checkstyle-plugin</artifactId> <version>${checkstyle.plugin.version}</version> <configuration> @@ -347,6 +369,28 @@ </reportSets> </plugin> <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>${commons.javadoc.version}</version> + <configuration> + <!-- keep only errors and warnings --> + <show>private</show> + <quiet>true</quiet> + <encoding>${commons.encoding}</encoding> + <notimestamp>true</notimestamp> + <links> + <link>${commons.javadoc.java.link}</link> + <link>${commons.javadoc.javaee.link}</link> + </links> + <archive> + <manifest> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries> + </manifest> + </archive> + </configuration> + </plugin> + <plugin> <artifactId>maven-checkstyle-plugin</artifactId> <version>${checkstyle.plugin.version}</version> <configuration> http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/7b1b50f4/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionStagingMojo.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionStagingMojo.java b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionStagingMojo.java index 0b44b77..6fd311d 100644 --- a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionStagingMojo.java +++ b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionStagingMojo.java @@ -36,14 +36,15 @@ import org.apache.maven.scm.provider.svn.svnexe.SvnExeScmProvider; import org.apache.maven.scm.repository.ScmRepository; import java.io.File; +import java.io.IOException; import java.util.ArrayList; import java.util.Arrays; import java.util.List; /** * This class checks out the dev distribution location, copies the distributions into that directory - * structure under the <code>target</code> directory. Then commits the distributions back up to SVN. - * Also, we include the built and zipped site as well as the RELEASE-NOTES.txt. + * structure under the <code>target/commons-release-plugin/scm</code> directory. Then commits the + * distributions back up to SVN. Also, we include the built and zipped site as well as the RELEASE-NOTES.txt. * * @author chtompki * @since 1.0 @@ -52,41 +53,58 @@ import java.util.List; public class CommonsDistributionStagingMojo extends AbstractMojo { /** + * The {@link MavenProject} object is essentially the context of the maven build at + * a given time. */ - @Parameter(defaultValue = "${project}", required = true ) + @Parameter(defaultValue = "${project}", required = true) private MavenProject project; /** + * The {@link File} that contains a file to the root directory of the working project. Typically + * this directory is where the <code>pom.xml</code> resides. */ @Parameter(defaultValue = "${basedir}") private File basedir; /** + * The main working directory for the plugin, namely <code>target/commons-release-plugin</code>, but + * that assumes that we're using the default maven <code>${project.build.directory}</code>. */ @Parameter(defaultValue = "${project.build.directory}/commons-release-plugin", alias = "outputDirectory") private File workingDirectory; /** + * The location to which to checkout the dist subversion repository under our working directory, which + * was given above. */ @Parameter(defaultValue = "${project.build.directory}/commons-release-plugin/scm", alias = "outputDirectory") private File distCheckoutDirectory; /** + * A boolean that determines whether or not we actually commit the files up to the subversion repository. + * If this is set to <code>true</code>, we do all but make the commits. We do checkout the repository in question + * though. */ @Parameter(defaultValue = "false") private Boolean dryRun; /** + * The url of the subversion repository to which we wish the artifacts to be staged. Typicallly + * this would need to be of the form: + * <code>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</code>. Note. that the prefix to the + * substring <code>https</code> is a requirement. */ @Parameter(required = true) private String distSvnStagingUrl; /** + * The username for the distribution subversion repository. This is typically your apache id. */ @Parameter(property = "user.name") private String username; /** + * The password associated with {@link CommonsDistributionStagingMojo#username}. */ @Parameter(property = "user.password") private String password; @@ -129,7 +147,9 @@ public class CommonsDistributionStagingMojo extends AbstractMojo { ); if (!checkInResult.isSuccess()) { getLog().error("Committing dist files failed: " + checkInResult.getCommandOutput()); - throw new MojoExecutionException("Committing dist files failed: " + checkInResult.getCommandOutput()); + throw new MojoExecutionException( + "Committing dist files failed: " + checkInResult.getCommandOutput() + ); } } else { getLog().error("Adding dist files failed: " + addResult.getCommandOutput()); @@ -145,6 +165,13 @@ public class CommonsDistributionStagingMojo extends AbstractMojo { } } + /** + * A utility method that takes the <code>RELEASE-NOTES.txt</code> file from the base directory of the + * project and copies it into {@link CommonsDistributionStagingMojo#workingDirectory}. + * + * @throws MojoExecutionException if an {@link IOException} occurrs as a wrapper so that maven + * can properly handle the exception. + */ private void copyReleaseNotesToWorkingDirectory() throws MojoExecutionException { StringBuffer copiedReleaseNotesAbsolutePath; getLog().info("Copying RELEASE-NOTES.txt to working directory."); @@ -156,6 +183,29 @@ public class CommonsDistributionStagingMojo extends AbstractMojo { SharedFunctions.copyFile(getLog(), releaseNotes, copiedReleaseNotes); } + /** + * Copies the list of files at the root of the {@link CommonsDistributionStagingMojo#workingDirectory} into + * the directory structure of the distribution staging repository. Specifically: + * <ul> + * <li>root:</li> + * <li><ul> + * <li>site.zip</li> + * <li>RELEASE-NOTES.txt</li> + * <li>source:</li> + * <li><ul> + * <li>-src artifacts....</li> + * </ul></li> + * <li>binaries:</li> + * <li><ul> + * <li>-bin artifacts....</li> + * </ul></li> + * </ul></li> + * </ul> + * + * @return a {@link List} of {@link File}'s in the directory for the purpose of adding them to the maven + * {@link ScmFileSet}. + * @throws MojoExecutionException if an {@link IOException} occurrs so that Maven can handle it properly. + */ private List<File> copyDistributionsIntoScmDirectoryStructure() throws MojoExecutionException { List<File> workingDirectoryFiles = Arrays.asList(workingDirectory.listFiles()); String scmBinariesRoot = buildDistBinariesRoot(); @@ -171,7 +221,8 @@ public class CommonsDistributionStagingMojo extends AbstractMojo { copy = new File(scmBinariesRoot + "/" + file.getName()); SharedFunctions.copyFile(getLog(), file, copy); filesForMavenScmFileSet.add(copy); - } else if (file.getName().contains("scm")){ + } else if (file.getName().contains("scm")) { + getLog().debug("Not copying scm directory over to the scm directory because it is the scm directory."); //do nothing because we are copying into scm } else { copy = new File(distCheckoutDirectory.getAbsolutePath() + "/" + file.getName()); @@ -183,18 +234,37 @@ public class CommonsDistributionStagingMojo extends AbstractMojo { return filesForMavenScmFileSet; } + /** + * Build the path for the distribution binaries directory. + * + * @return the local absolute path into the checkedout subversion repository that is where + * the binaries distributions are to be copied. + */ private String buildDistBinariesRoot() { StringBuffer buffer = new StringBuffer(distCheckoutDirectory.getAbsolutePath()); buffer.append("/binaries"); return buffer.toString(); } + /** + * Build the path for the distribution source directory. + * + * @return the local absolute path into the checkedout subversion repository that is where + * the source distributions are to be copied. + */ private String buildDistSourceRoot() { StringBuffer buffer = new StringBuffer(distCheckoutDirectory.getAbsolutePath()); buffer.append("/source"); return buffer.toString(); } + /** + * This method is the setter for the {@link CommonsDistributionStagingMojo#basedir} field, specifically + * for the usage in the unit tests. + * + * @param basedir is the {@link File} to be used as the project's root directory when this mojo + * is invoked. + */ protected void setBasedir(File basedir) { this.basedir = basedir; } http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/7b1b50f4/src/site/xdoc/index.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml index cb38844..2c1cbe8 100644 --- a/src/site/xdoc/index.xml +++ b/src/site/xdoc/index.xml @@ -125,12 +125,14 @@ <li> running the following command: <source><![CDATA[ -mvn -Duser.name=<yourApacheId> -Prelease clean test site deploy +mvn -Duser.name=<yourApacheId> [-Duser.password=<yourApacheIdsPassword] [-DdryRun=true -Ptest-deploy] -Prelease clean test site deploy ]]></source> </li> </ol> - If the component is new, then, before running this maven command, you would want to create - the requisite subversion directory <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>. + If the component is new, then, before running this maven command, you would want to create + the requisite subversion directory <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>. Notice, + that the way to perform a dry run of the release you need to include + <code>-DdryRun=true -Ptest-deploy</code>. </p> </section>
