Skip to content
Permalink
Browse files
COMMONSSITE-97: More documentation
  • Loading branch information
chtompki committed Jan 9, 2018
1 parent 9a2db79 commit 7b1b50f4b0eaadebcb46cdcd2c79ac042e50845f
Showing 4 changed files with 125 additions and 9 deletions.
@@ -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].

[![Build Status](https://travis-ci.org/apache/commons-release-plugin.svg?branch=trunk)](https://travis-ci.org/apache/commons-release-plugin)
[![Build Status](https://travis-ci.org/apache/commons-release-plugin.svg?branch=master)](https://travis-ci.org/apache/commons-release-plugin)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-release-plugin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-release-plugin)

Where can I get the latest release?
44 pom.xml
@@ -196,6 +196,28 @@
</plugins>
</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>
@@ -346,6 +368,28 @@
<reportSet/>
</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>
@@ -36,14 +36,15 @@
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 @@
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 void execute() throws MojoExecutionException, MojoFailureException {
);
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 void execute() throws MojoExecutionException, MojoFailureException {
}
}

/**
* 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 @@ private void copyReleaseNotesToWorkingDirectory() throws MojoExecutionException
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 @@ private List<File> copyDistributionsIntoScmDirectoryStructure() throws MojoExecu
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 @@ private List<File> copyDistributionsIntoScmDirectoryStructure() throws MojoExecu
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;
}
@@ -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>

0 comments on commit 7b1b50f

Please sign in to comment.