This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-release-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 22f1a2d Javadoc and other documentation.
22f1a2d is described below
commit 22f1a2d5f3f9ec14cdfff687dabc185c78eae6dd
Author: Gary Gregory <[email protected]>
AuthorDate: Tue Sep 15 08:39:26 2026 -0700
Javadoc and other documentation.
---
CONTRIBUTING.md | 10 ++--
README.md | 4 +-
.../commons/release/plugin/SharedFunctions.java | 25 +++++----
.../mojos/CommonsDistributionDetachmentMojo.java | 30 +++++------
.../mojos/CommonsDistributionStagingMojo.java | 62 ++++++++++------------
.../plugin/mojos/CommonsSiteCompressionMojo.java | 21 ++++----
.../plugin/mojos/CommonsStagingCleanupMojo.java | 18 +++----
.../commons/release/plugin/mojos/package-info.java | 2 +-
.../commons/release/plugin/package-info.java | 2 +-
.../release/plugin/slsa/v1_2/DsseEnvelope.java | 2 +-
.../release/plugin/slsa/v1_2/Statement.java | 2 +-
.../velocity/HeaderHtmlVelocityDelegate.java | 10 ++--
.../velocity/ReadmeHtmlVelocityDelegate.java | 30 +++++------
.../release/plugin/velocity/package-info.java | 5 +-
.../commons-xdoc-templates/vote-txt-template.txt | 24 ++++-----
.../commons/release/plugin/velocity/README.vm | 4 +-
src/main/scripts/generate-xdocs.mojos.xml | 14 ++---
src/site/xdoc/development.xml | 39 +++++++-------
src/site/xdoc/download_release-plugin.xml | 2 +-
src/site/xdoc/index.xml | 45 ++++++++--------
src/site/xdoc/issue-tracking.xml | 10 ++--
src/site/xdoc/mail-lists.xml | 2 +-
src/site/xdoc/vote-txt.xml | 12 ++---
.../commons/release/plugin/stubs/package-info.java | 6 +--
24 files changed, 185 insertions(+), 196 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 16c7ee7..22c3fb9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,7 +41,7 @@
Contributing to Apache Commons Release Plugin
======================
-Have you found a bug or have an idea for a cool new feature? Contributing code
is a great way to give something back to the open-source community.
+Have you found a bug or do you have an idea for a cool new feature?
Contributing code is a great way to give something back to the open-source
community.
Before you dig right into the code, we need contributors to follow a few
guidelines to have a chance of keeping on top of things.
Getting Started
@@ -49,7 +49,7 @@ Getting Started
+ Make sure you have a [JIRA account](https://issues.apache.org/jira/).
+ Make sure you have a [GitHub account](https://github.com/signup). This is
not essential, but makes providing patches much easier.
-+ If you're planning to implement a new feature it makes sense to discuss your
changes on the [dev list](https://commons.apache.org/mail-lists.html) first.
This way you can make sure you're not wasting your time on something that isn't
considered to be in Apache Commons Release Plugin's scope.
++ If you're planning to implement a new feature, it makes sense to discuss
your changes on the [dev list](https://commons.apache.org/mail-lists.html)
first. This way you can make sure you're not wasting your time on something
that isn't considered to be in Apache Commons Release Plugin's scope.
+ Submit a [Jira Ticket][jira] for your issue, assuming one does not already
exist.
+ Clearly describe the issue including steps to reproduce when it is a bug.
+ Make sure you fill in the earliest version that you know has the issue.
@@ -60,7 +60,7 @@ Making Changes
--------------
+ Create a _topic branch_ for your isolated work.
- * Usually you should base your branch from the `master` branch.
+ * Usually you should base your branch on the `master` branch.
* A good topic branch name can be the JIRA bug ID plus a keyword, e.g.
`COMMONSSITE-123-InputStream`.
* If you have submitted multiple JIRA issues, try to maintain separate
branches and pull requests.
+ Make commits of logical units.
@@ -68,7 +68,7 @@ Making Changes
* For example, `[COMMONSSITE-123] Close input stream sooner`
+ Respect the original code style:
+ Only use spaces for indentation; you can check for unnecessary whitespace
with `git diff` before committing.
- + Create minimal diffs - disable _On Save_ actions like _Reformat Source
Code_ or _Organize Imports_. If you feel the source code should be reformatted
create a separate PR for this change first.
+ + Create minimal diffs - disable _On Save_ actions like _Reformat Source
Code_ or _Organize Imports_. If you feel the source code should be reformatted,
create a separate PR for this change first.
+ Write unit tests that match behavioral changes, where the tests fail if the
changes to the runtime are not applied. This may not always be possible but is
a best practice.
Unit tests are typically in the `src/test/java` directory.
+ Run a successful build using the default [Maven](https://maven.apache.org/)
goal with `mvn`; that's `mvn` on the command line by itself.
@@ -95,7 +95,7 @@ Submitting Changes
+ Push your changes to a topic branch in your fork of the repository.
+ Submit a _Pull Request_ to the corresponding repository in the `apache`
organization.
* Verify _Files Changed_ shows only your intended changes and does not
- include additional files like `target/*.class`
+ include additional files like `target/*.class`.
+ Update your JIRA ticket and include a link to the pull request in the ticket.
If you prefer to not use GitHub, then you can instead use
diff --git a/README.md b/README.md
index 183f325..761a816 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ We accept Pull Requests via GitHub. The [developer mailing
list](https://commons
There are some guidelines which will make applying PRs easier for us:
+ No tabs! Please use spaces for indentation.
+ Respect the existing code style for each file.
-+ Create minimal diffs - disable on save actions like reformat source code or
organize imports. If you feel the source code should be reformatted create a
separate PR for this change.
++ Create minimal diffs - disable on-save actions like reformatting source code
or organizing imports. If you feel the source code should be reformatted,
create a separate PR for this change.
+ Provide JUnit tests for your changes and make sure your changes don't break
any existing tests by running `mvn`.
+ Before you push a PR, run `mvn` (without arguments). This runs the default
goal which contains all build checks.
+ To see the code coverage report, regardless of coverage failures, run `mvn
clean site -Dcommons.jacoco.haltOnFailure=false -Pjacoco`
@@ -115,4 +115,4 @@ Additional Resources
Apache Commons Components
-------------------------
-Please see the [list of components](https://commons.apache.org/components.html)
+Please see the [list of
components](https://commons.apache.org/components.html).
diff --git
a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
b/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
index f983c5e..1ebfc66 100644
--- a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
+++ b/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
@@ -48,10 +48,10 @@ public final class SharedFunctions {
* Copies a {@link File} from the <code>fromFile</code> to the
<code>toFile</code> and logs the failure
* using the Maven {@link Log}.
*
- * @param log The {@link Log}, the maven logger.
+ * @param log The {@link Log}, the Maven logger.
* @param fromFile The {@link File} from which to copy.
- * @param toFile The {@link File} to which to copy into.
- * @throws MojoExecutionException if an {@link IOException} or {@link
NullPointerException} is caught.
+ * @param toFile The destination {@link File}.
+ * @throws MojoExecutionException Thrown if an {@link IOException} or
{@link NullPointerException} is caught.
*/
public static void copyFile(final Log log, final File fromFile, final File
toFile) throws MojoExecutionException {
final String format = "Unable to copy file %s to %s: %s";
@@ -70,10 +70,9 @@ public final class SharedFunctions {
* Cleans and then initializes an empty directory that is given by the
<code>workingDirectory</code>
* parameter.
*
- * @param log is the Maven log for output logging, particularly in regards
to error management.
- * @param workingDirectory is a {@link File} that represents the directory
to first attempt to delete then create.
- * @throws MojoExecutionException when an {@link IOException} or {@link
NullPointerException} is caught for the
- * purpose of bubbling the exception up to Maven properly.
+ * @param log is the Maven log for output logging, particularly with
regard to error management.
+ * @param workingDirectory is a {@link File} that represents the directory
to first attempt to delete and then create.
+ * @throws MojoExecutionException Thrown if an {@link IOException} or
{@link NullPointerException} is caught.
*/
public static void initDirectory(final Log log, final File
workingDirectory) throws MojoExecutionException {
final String format = "Unable to remove directory %s: %s";
@@ -107,7 +106,7 @@ public final class SharedFunctions {
* @param obj The object reference to check for nullity
* @param <T> The type of the reference
* @return {@code obj} if not {@code null}
- * @throws MojoExecutionException if {@code obj} is {@code null}
+ * @throws MojoExecutionException Thrown if {@code obj} is {@code null}.
*/
public static <T> T requireNonNull(final T obj) throws
MojoExecutionException {
if (obj == null) {
@@ -134,7 +133,7 @@ public final class SharedFunctions {
* NullPointerException} is thrown
* @param <T> The type of the reference
* @return {@code obj} if not {@code null}
- * @throws MojoExecutionException if {@code obj} is {@code null}
+ * @throws MojoExecutionException Thrown if {@code obj} is {@code null}.
*/
public static <T> T requireNonNull(final T obj, final String message)
throws MojoExecutionException {
if (obj == null) {
@@ -147,15 +146,15 @@ public final class SharedFunctions {
* Checks that the specified object reference is not {@code null} and
throws a customized {@link MojoExecutionException} if it is.
* <p>
* Unlike the method {@link #requireNonNull(Object, String)}, this method
allows creation of the message to be deferred until after the null check is
made.
- * While this may confer a performance advantage in the non-null case,
when deciding to call this method care should be taken that the costs of
creating the
- * message supplier are less than the cost of just creating the string
message directly.
+ * While this may confer a performance advantage in the non-null case,
when deciding to call this method, care should be taken that the costs of
creating
+ * the message supplier are less than the cost of just creating the string
message directly.
* </p>
*
* @param obj The object reference to check for nullity
* @param messageSupplier supplier of the detail message to be used in the
event that a {@code NullPointerException} is thrown
* @param <T> The type of the reference
* @return {@code obj} if not {@code null}
- * @throws MojoExecutionException if {@code obj} is {@code null}
+ * @throws MojoExecutionException Thrown if {@code obj} is {@code null}.
*/
public static <T> T requireNonNull(final T obj, final Supplier<String>
messageSupplier) throws MojoExecutionException {
if (obj == null) {
@@ -189,7 +188,7 @@ public final class SharedFunctions {
}
/**
- * Making the constructor private because the class only contains static
methods.
+ * Prevents instantiation of this utility class.
*/
private SharedFunctions() {
// Utility Class
diff --git
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java
index f953d95..a9ebd6f 100644
---
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java
+++
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java
@@ -43,7 +43,7 @@ import org.apache.maven.project.MavenProject;
/**
* The purpose of this Maven mojo is to detach the artifacts generated by the
maven-assembly-plugin,
- * which for the Apache Commons Project do not get uploaded to Nexus, and
putting those artifacts
+ * which for the Apache Commons Project do not get uploaded to Nexus, and put
those artifacts
* in the dev distribution location for Apache projects.
*
* @since 1.0
@@ -56,10 +56,10 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
/**
* A list of "artifact types" in the Maven vernacular, to
- * be detached from the deployment. For the time being we want
+ * be detached from the deployment. For the time being, we want
* all artifacts generated by the maven-assembly-plugin to be detached
* from the deployment, namely *-src.zip, *-src.tar.gz, *-bin.zip,
- * *-bin.tar.gz, and the corresponding .asc pgp signatures.
+ * *-bin.tar.gz, and the corresponding .asc PGP signatures.
*/
private static final Set<String> ARTIFACT_TYPES_TO_DETACH;
@@ -74,7 +74,7 @@ public final class CommonsDistributionDetachmentMojo extends
AbstractMojo {
/**
* This list is supposed to hold the Maven references to the
aforementioned artifacts so that we
- * can upload them to svn after they've been detached from the Maven
deployment.
+ * can upload them to SVN after they've been detached from the Maven
deployment.
*/
private final List<Artifact> detachedArtifacts = new ArrayList<>();
@@ -86,7 +86,7 @@ public final class CommonsDistributionDetachmentMojo extends
AbstractMojo {
private final SortedProperties artifactSha512s = new SortedProperties();
/**
- * The maven project context injection so that we can get a hold of the
variables at hand.
+ * The Maven project context injection so that we can get a hold of the
variables at hand.
*/
@Parameter(defaultValue = "${project}", required = true)
private MavenProject project;
@@ -99,7 +99,7 @@ public final class CommonsDistributionDetachmentMojo extends
AbstractMojo {
private File workingDirectory;
/**
- * The subversion staging url to which we upload all of our staged
artifacts.
+ * The Subversion staging URL to which we upload all of our staged
artifacts.
*/
@Parameter(defaultValue = "", property = "commons.distSvnStagingUrl")
private String distSvnStagingUrl;
@@ -121,8 +121,7 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
* A helper method to copy the newly detached artifacts to
<code>target/commons-release-plugin</code>
* so that the {@link CommonsDistributionStagingMojo} can find the
artifacts later.
*
- * @throws MojoExecutionException if some form of an {@link IOException}
occurs, we want it
- * properly wrapped so that Maven can
handle it.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
private void copyRemovedArtifactsToWorkingDirectory() throws
MojoExecutionException {
final String wdAbsolutePath = workingDirectory.getAbsolutePath();
@@ -189,7 +188,7 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * Generates the unique artifact key for storage in our sha512 map. For
example,
+ * Gets the unique artifact key for storage in our sha512 map. For example,
* commons-test-1.4-src.tar.gz should have its name as the key.
*
* @param artifact The {@link Artifact} that we wish to generate a key for.
@@ -200,7 +199,7 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * A helper method to create a file path for the <code>sha512</code>
signature file from a given file.
+ * Gets the file path for the <code>sha512</code> signature file for a
given file.
*
* @param directory is the {@link File} for the directory in which to make
the <code>.sha512</code> file.
* @param file The {@link File} whose name we should use to create the
<code>.sha512</code> file.
@@ -219,8 +218,7 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
* <code>target/commons-release-plugin</code> directory for the purpose
of being uploaded by
* the {@link CommonsDistributionStagingMojo}.
*
- * @throws MojoExecutionException if some form of an {@link IOException}
occurs, we want it
- * properly wrapped so that Maven can
handle it.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
private void hashArtifacts() throws MojoExecutionException {
for (final Artifact artifact : detachedArtifacts) {
@@ -245,8 +243,8 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
/**
* Takes an attached artifact and puts the signature in the map.
*
- * @param artifact is a Maven {@link Artifact} taken from the project at
start time of mojo.
- * @throws MojoExecutionException if an {@link IOException} occurs when
getting the sha512 of the
+ * @param artifact is a Maven {@link Artifact} taken from the project when
the mojo starts.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs
when getting the sha512 of the
* artifact.
*/
private void putAttachedArtifactInSha512Map(final Artifact artifact)
throws MojoExecutionException {
@@ -272,9 +270,9 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * Writes to ./target/commons-release-plugin/sha512.properties the
artifact sha512's.
+ * Writes the artifacts' SHA-512 hashes to
./target/commons-release-plugin/sha512.properties.
*
- * @throws MojoExecutionException if we can't write the file due to an
{@link IOException}.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs
while writing the file.
*/
private void writeAllArtifactsInSha512PropertiesFile() throws
MojoExecutionException {
final File propertiesFile = new File(workingDirectory,
"sha512.properties");
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 1270d30..d34f5cf 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
@@ -59,9 +59,9 @@ import org.apache.maven.settings.Settings;
import org.apache.maven.settings.crypto.SettingsDecrypter;
/**
- * This class checks out the dev distribution location, copies the
distributions into that directory
- * 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.
+ * Checks out the dev distribution location, copies the distributions into
that directory
+ * structure under the <code>target/commons-release-plugin/scm</code>
directory, and commits the
+ * distributions back to SVN. Includes the built and zipped site as well as
the RELEASE-NOTES.txt file.
*
* @since 1.0
*/
@@ -71,42 +71,42 @@ import org.apache.maven.settings.crypto.SettingsDecrypter;
aggregator = true)
public final class CommonsDistributionStagingMojo extends AbstractMojo {
- /** The name of file generated from the README.vm velocity template to be
checked into the dist svn repo. */
+ /** The name of the file generated from the README.vm Velocity template to
be checked into the dist SVN repo. */
private static final String README_FILE_NAME = "README.html";
- /** The name of file generated from the HEADER.vm velocity template to be
checked into the dist svn repo. */
+ /** The name of the file generated from the HEADER.vm Velocity template to
be checked into the dist SVN repo. */
private static final String HEADER_FILE_NAME = "HEADER.html";
- /** The name of the signature validation shell script to be checked into
the dist svn repo. */
+ /** The name of the signature validation shell script to be checked into
the dist SVN repo. */
private static final String SIGNATURE_VALIDATOR_NAME =
"signature-validator.sh";
/**
- * The {@link MavenProject} object is essentially the context of the maven
build at
+ * The {@link MavenProject} object is essentially the context of the Maven
build at
* a given time.
*/
@Parameter(defaultValue = "${project}", required = true)
private MavenProject project;
/**
- * The {@link File} that contains a file to the root directory of the
working project. Typically
+ * The {@link File} representing 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 location to which the site gets built during running <code>mvn
site</code>. */
+ /** The location to which the site gets built when running <code>mvn
site</code>. */
@Parameter(defaultValue = "${project.build.directory}/site", property =
"commons.siteOutputDirectory")
private File siteDirectory;
/**
* 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>.
+ * that assumes that we're using the default Maven
<code>${project.build.directory}</code>.
*/
@Parameter(defaultValue =
"${project.build.directory}/commons-release-plugin", property =
"commons.outputDirectory")
private File workingDirectory;
/**
- * The location to which to check out the dist subversion repository under
our working directory, which
+ * The location to which to check out the dist Subversion repository under
our working directory, which
* was given above.
*/
@Parameter(defaultValue =
"${project.build.directory}/commons-release-plugin/scm",
@@ -120,16 +120,16 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
private File releaseNotesFile;
/**
- * A boolean that determines whether or not we actually commit the files
up to the subversion repository.
- * If this is set to {@code true}, we do all but make the commits. We do
checkout the repository in question
+ * A boolean that determines whether or not we actually commit the files
up to the Subversion repository.
+ * If this is set to {@code true}, we do all but make the commits. We do
check out the repository in question,
* though.
*/
@Parameter(property = "commons.release.dryRun", defaultValue = "false")
private Boolean dryRun;
/**
- * The url of the subversion repository to which we wish the artifacts to
be staged. Typically this would need to
- * be of the form:
<code>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo/version-RC#</code>.
Note. that
+ * The URL of the Subversion repository to which we wish the artifacts to
be staged. Typically this would need to
+ * be of the form:
<code>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo/version-RC#</code>.
Note that
* the prefix to the substring <code>https</code> is a requirement.
*/
@Parameter(defaultValue = "", property = "commons.distSvnStagingUrl")
@@ -148,7 +148,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
private String commonsReleaseVersion;
/**
- * The RC version of the release. For example the first voted on candidate
would be "RC1".
+ * The RC version of the release. For example, the first release candidate
would be "RC1".
*/
@Parameter(property = "commons.rc.version")
private String commonsRcVersion;
@@ -161,7 +161,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
private String distServer;
/**
- * The username for the distribution subversion repository. This is
typically your Apache id.
+ * The username for the distribution Subversion repository. This is
typically your Apache ID.
*/
@Parameter(property = "user.name")
private String username;
@@ -186,7 +186,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
/**
* A subdirectory of the dist directory into which we are going to stage
the release candidate. We
- * build this up in the {@link CommonsDistributionStagingMojo#execute()}
method. And, for example,
+ * build this up in the {@link CommonsDistributionStagingMojo#execute()}
method. For example,
* the directory should look like
<code>https://dist.apache.org/repos/dist/dev/commons/text/1.4-RC1</code>.
*/
private File distRcVersionDirectory;
@@ -199,7 +199,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
}
/**
- * Builds up <code>README.html</code> and <code>HEADER.html</code> that
reside in following.
+ * Builds up <code>README.html</code> and <code>HEADER.html</code> that
reside in the following directory structure:
* <ul>
* <li>distRoot
* <ul>
@@ -214,8 +214,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
* </ul>
*
* @return The {@link List} of created files above
- * @throws MojoExecutionException if an {@link IOException} occurs in the
creation of these
- * files fails.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs
while creating these files.
*/
private List<File> buildReadmeAndHeaderHtmlFiles() throws
MojoExecutionException {
final List<File> headerAndReadmeFiles = new ArrayList<>();
@@ -286,9 +285,9 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
*
<code>target/commons-release-plugin/scm</code> directory.
* @param provider is the {@link ScmProvider} that we will use for adding
the files we wish to commit.
* @param repository is the {@link ScmRepository} that we will use for
adding the files that we wish to commit.
- * @return A {@link List} of {@link File}'s in the directory for the
purpose of adding them to the maven
+ * @return A {@link List} of {@link File} objects in the directory for the
purpose of adding them to the Maven
* {@link ScmFileSet}.
- * @throws MojoExecutionException if an {@link IOException} occurs so that
Maven can handle it properly.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
private List<File>
copyDistributionsIntoScmDirectoryStructureAndAddToSvn(final File
copiedReleaseNotes,
final ScmProvider provider,
@@ -332,8 +331,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
* @param headerFile The originally created <code>HEADER.html</code> file.
* @param readmeFile The originally created <code>README.html</code> file.
* @return A {@link List} of created files.
- * @throws MojoExecutionException if the {@link
SharedFunctions#copyFile(Log, File, File)}
- * fails.
+ * @throws MojoExecutionException Thrown if {@link
SharedFunctions#copyFile(Log, File, File)} fails.
*/
private List<File> copyHeaderAndReadmeToSubdirectories(final File
headerFile, final File readmeFile)
throws MojoExecutionException {
@@ -363,8 +361,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
* directory for the purpose of adding it to the scm change set in
the method
* {@link
CommonsDistributionStagingMojo#copyDistributionsIntoScmDirectoryStructureAndAddToSvn(File,
* ScmProvider, ScmRepository)}.
- * @throws MojoExecutionException if an {@link IOException} occurs as a
wrapper so that maven
- * can properly handle the exception.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs
while copying the file.
*/
private File copyReleaseNotesToWorkingDirectory() throws
MojoExecutionException {
SharedFunctions.initDirectory(getLog(), distRcVersionDirectory);
@@ -379,7 +376,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
*
<code>${basedir}/target/commons-release-plugin/scm/signature-validator.sh</code>.
*
* @return The {@link File} for the signature-validator.sh
- * @throws MojoExecutionException if an error occurs while the resource is
being copied
+ * @throws MojoExecutionException Thrown if an error occurs while copying
the resource.
*/
private File copySignatureValidatorScriptToScmDirectory() throws
MojoExecutionException {
final Path scmTargetPath =
Paths.get(distRcVersionDirectory.toString(), SIGNATURE_VALIDATOR_NAME);
@@ -396,9 +393,9 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
/**
* Copies <code>${basedir}/target/site</code> to
<code>${basedir}/target/commons-release-plugin/scm/site</code>.
*
- * @return The {@link List} of {@link File}'s contained in
+ * @return The {@link List} of {@link File} objects contained in
* <code>${basedir}/target/commons-release-plugin/scm/site</code>,
after the copy is complete.
- * @throws MojoExecutionException if the site copying fails for some
reason.
+ * @throws MojoExecutionException Thrown if an error occurs while copying
the site.
*/
private List<File> copySiteToScmDirectory() throws MojoExecutionException {
if (!siteDirectory.exists()) {
@@ -499,7 +496,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
}
/**
- * Lists all directories and files to a flat list.
+ * Lists all directories and files in a flat list.
*
* @param directory {@link File} containing directory to list
* @param files A {@link List} of {@link File} to which to append the
files.
@@ -518,8 +515,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
}
/**
- * This method is the setter for the {@link
CommonsDistributionStagingMojo#baseDir} field, specifically
- * for the usage in the unit tests.
+ * Sets the {@link CommonsDistributionStagingMojo#baseDir} field for use
in unit tests.
*
* @param baseDir is the {@link File} to be used as the project's root
directory when this mojo
* is invoked.
diff --git
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsSiteCompressionMojo.java
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsSiteCompressionMojo.java
index 9026748..9468636 100644
---
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsSiteCompressionMojo.java
+++
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsSiteCompressionMojo.java
@@ -51,8 +51,8 @@ import org.apache.maven.plugins.annotations.Parameter;
public final class CommonsSiteCompressionMojo extends AbstractMojo {
/**
- * The working directory for the plugin which, assuming the maven uses the
default
- * <code>${project.build.directory}</code>, this becomes
<code>target/commons-release-plugin</code>.
+ * The working directory for the plugin, which is
<code>target/commons-release-plugin</code> when Maven uses
+ * the default <code>${project.build.directory}</code>.
*/
@Parameter(defaultValue =
"${project.build.directory}/commons-release-plugin",
property = "commons.outputDirectory")
@@ -65,9 +65,9 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
private File siteDirectory;
/**
- * The url of the subversion repository to which we wish the artifacts to
be staged. Typically
+ * The URL of the Subversion repository to which we wish the artifacts to
be staged. Typically
* 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
+ *
<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(defaultValue = "", property = "commons.distSvnStagingUrl")
@@ -92,14 +92,13 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
}
/**
- * Given the <code>directoryToZip</code> we add the <code>file</code> to
the ZIP archive represented by
+ * Given the <code>directoryToZip</code>, we add the <code>file</code> to
the ZIP archive represented by
* <code>zos</code>.
*
- * @param directoryToZip A {@link File} representing the directory from
which the file exists that we are
- * compressing. Generally this is
<code>target/site</code>.
+ * @param directoryToZip A {@link File} representing the directory
containing the file to compress. Generally, this is <code>target/site</code>.
* @param file A {@link File} to add to the {@link ZipOutputStream}
<code>zos</code>.
* @param zos The {@link ZipOutputStream} to which to add our
<code>file</code>.
- * @throws IOException Thrown if adding the <code>file</code> doesn't work
out properly.
+ * @throws IOException Thrown if an error occurs while adding the
<code>file</code> to the ZIP archive.
*/
private void addToZip(final File directoryToZip, final File file, final
ZipOutputStream zos) throws IOException {
try (InputStream fis = Files.newInputStream(file.toPath())) {
@@ -149,8 +148,8 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
}
/**
- * By default this method iterates across the <code>target/site</code>
directory and adds all the files
- * to the {@link CommonsSiteCompressionMojo#filesToCompress} {@link List}.
+ * Gets all site files and adds them to the {@link
CommonsSiteCompressionMojo#filesToCompress} {@link List}.
+ * This method searches the <code>target/site</code> directory by default.
*
* @param siteDirectory The {@link File} that represents the
<code>target/site</code> directory.
* @param filesToCompress The {@link List} to which to add all the files.
@@ -174,7 +173,7 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
* <code>target/site</code>).
* @param fileList The list of files to be zipped up, generally generated
by
* {@link CommonsSiteCompressionMojo#getAllSiteFiles(File,
List)}.
- * @throws IOException when the copying of the files goes incorrectly.
+ * @throws IOException Thrown if an error occurs while copying the files.
*/
private void writeZipFile(final File outputDirectory, final File
directoryToZip, final List<File> fileList)
throws IOException {
diff --git
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojo.java
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojo.java
index afbb891..e27c9ab 100644
---
a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojo.java
+++
b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojo.java
@@ -46,7 +46,7 @@ import org.apache.maven.settings.crypto.SettingsDecrypter;
/**
* This class checks out the dev distribution location, checks whether
anything exists in the
- * distribution location, and if it is non-empty it deletes all the resources
there.
+ * distribution location, and, if it is non-empty, deletes all the resources
there.
*
* @since 1.6
*/
@@ -57,7 +57,7 @@ import org.apache.maven.settings.crypto.SettingsDecrypter;
public final class CommonsStagingCleanupMojo extends AbstractMojo {
/**
- * The {@link MavenProject} object is essentially the context of the maven
build at
+ * The {@link MavenProject} object is essentially the context of the Maven
build at
* a given time.
*/
@Parameter(defaultValue = "${project}", required = true)
@@ -65,13 +65,13 @@ public final class CommonsStagingCleanupMojo extends
AbstractMojo {
/**
* 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>.
+ * that assumes that we're using the default Maven
<code>${project.build.directory}</code>.
*/
@Parameter(defaultValue =
"${project.build.directory}/commons-release-plugin", property =
"commons.outputDirectory")
private File workingDirectory;
/**
- * The location to which to checkout the dist subversion repository under
our working directory, which
+ * The location to which to check out the dist Subversion repository under
our working directory, which
* was given above. We then do an SVN delete on all the directories in
this repository.
*/
@Parameter(defaultValue =
"${project.build.directory}/commons-release-plugin/scm-cleanup",
@@ -79,16 +79,16 @@ public final class CommonsStagingCleanupMojo extends
AbstractMojo {
private File distCleanupDirectory;
/**
- * A boolean that determines whether or not we actually commit the files
up to the subversion repository.
- * If this is set to {@code true}, we do all but make the commits. We do
checkout the repository in question
+ * A boolean that determines whether or not we actually commit the files
up to the Subversion repository.
+ * If this is set to {@code true}, we do all but make the commits. We do
check out the repository in question,
* though.
*/
@Parameter(property = "commons.release.dryRun", defaultValue = "false")
private Boolean dryRun;
/**
- * The url of the subversion repository to which we wish the artifacts to
be staged. Typically this would need to
- * be of the form:
<code>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo/version-RC#</code>.
Note. that
+ * The URL of the Subversion repository to which we wish the artifacts to
be staged. Typically this would need to
+ * be of the form:
<code>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo/version-RC#</code>.
Note that
* the prefix to the substring <code>https</code> is a requirement.
*/
@Parameter(defaultValue = "", property = "commons.distSvnStagingUrl")
@@ -108,7 +108,7 @@ public final class CommonsStagingCleanupMojo extends
AbstractMojo {
private String distServer;
/**
- * The username for the distribution subversion repository. This is
typically your Apache id.
+ * The username for the distribution Subversion repository. This is
typically your Apache ID.
*/
@Parameter(property = "user.name")
private String username;
diff --git
a/src/main/java/org/apache/commons/release/plugin/mojos/package-info.java
b/src/main/java/org/apache/commons/release/plugin/mojos/package-info.java
index 8ad0962..8e1c816 100644
--- a/src/main/java/org/apache/commons/release/plugin/mojos/package-info.java
+++ b/src/main/java/org/apache/commons/release/plugin/mojos/package-info.java
@@ -16,7 +16,7 @@
*/
/**
- * This package contains all the maven mojos for the commons-release-plugin.
Currently
+ * This package contains all the Maven mojos for the commons-release-plugin.
Currently,
* this only has the following mojos:
* <ul>
* <li>{@link
org.apache.commons.release.plugin.mojos.CommonsDistributionDetachmentMojo},</li>
diff --git a/src/main/java/org/apache/commons/release/plugin/package-info.java
b/src/main/java/org/apache/commons/release/plugin/package-info.java
index c00f5a2..f7887dc 100644
--- a/src/main/java/org/apache/commons/release/plugin/package-info.java
+++ b/src/main/java/org/apache/commons/release/plugin/package-info.java
@@ -17,7 +17,7 @@
/**
* Base package for the commons-release-plugin. It should contain only classes
- * that are used across all sub-packages. For now the only class in this
package
+ * that are used across all sub-packages. For now, the only class in this
package
* is:
* <ul>
* <li>{@link org.apache.commons.release.plugin.SharedFunctions}</li>
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/DsseEnvelope.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/DsseEnvelope.java
index c0ce9cb..685cb57 100644
---
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/DsseEnvelope.java
+++
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/DsseEnvelope.java
@@ -60,7 +60,7 @@ public class DsseEnvelope {
/**
* Gets the serialized payload bytes.
*
- * <p>When serialized to JSON the bytes are Base64-encoded.</p>
+ * <p>When serialized to JSON, the bytes are Base64-encoded.</p>
*
* @return The payload bytes, or {@code null} if not set.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Statement.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Statement.java
index b3d35b2..ce91203 100644
--- a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Statement.java
+++ b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Statement.java
@@ -56,7 +56,7 @@ public class Statement {
}
/**
- * Type of JSON object.
+ * Gets the JSON object type.
*
* @return Always {@value TYPE}.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/velocity/HeaderHtmlVelocityDelegate.java
b/src/main/java/org/apache/commons/release/plugin/velocity/HeaderHtmlVelocityDelegate.java
index fe811f2..c929350 100644
---
a/src/main/java/org/apache/commons/release/plugin/velocity/HeaderHtmlVelocityDelegate.java
+++
b/src/main/java/org/apache/commons/release/plugin/velocity/HeaderHtmlVelocityDelegate.java
@@ -25,7 +25,7 @@ import org.apache.velocity.runtime.RuntimeConstants;
import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
/**
- * This class' purpose is to generate the <code>HEADER.html</code> that moves
along with the
+ * This class's purpose is to generate the <code>HEADER.html</code> that moves
along with the
* release for the sake of downloading the release from the distribution area.
*
* @since 1.3
@@ -53,7 +53,7 @@ public final class HeaderHtmlVelocityDelegate {
}
}
- /** The location of the velocity template for this class. */
+ /** The location of the Velocity template for this class. */
private static final String TEMPLATE =
"resources/org/apache/commons/release/plugin/velocity/HEADER.vm";
/**
@@ -70,10 +70,10 @@ public final class HeaderHtmlVelocityDelegate {
}
/**
- * Builds the HEADER.vm velocity template to the writer passed in.
+ * Renders the HEADER.vm Velocity template to the supplied writer.
*
- * @param writer any {@link Writer} that we wish to have the filled
velocity template written to.
- * @return The {@link Writer} that we've filled out the template into.
+ * @param writer any {@link Writer} that we wish to have the filled
Velocity template written to.
+ * @return The {@link Writer} to which the template was rendered.
*/
public Writer render(final Writer writer) {
final VelocityEngine ve = new VelocityEngine();
diff --git
a/src/main/java/org/apache/commons/release/plugin/velocity/ReadmeHtmlVelocityDelegate.java
b/src/main/java/org/apache/commons/release/plugin/velocity/ReadmeHtmlVelocityDelegate.java
index 940c0cb..ad3273e 100644
---
a/src/main/java/org/apache/commons/release/plugin/velocity/ReadmeHtmlVelocityDelegate.java
+++
b/src/main/java/org/apache/commons/release/plugin/velocity/ReadmeHtmlVelocityDelegate.java
@@ -27,7 +27,7 @@ import org.apache.velocity.runtime.RuntimeConstants;
import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
/**
- * This class' purpose is to generate the <code>README.html</code> that moves
along with the
+ * This class's purpose is to generate the <code>README.html</code> that moves
along with the
* release for the sake of downloading the release from the distribution area.
*
* @since 1.3
@@ -39,13 +39,13 @@ public final class ReadmeHtmlVelocityDelegate {
*/
public static final class ReadmeHtmlVelocityDelegateBuilder {
- /** The maven artifactId to use in the <code>README.vm</code>
template. */
+ /** The Maven artifactId to use in the <code>README.vm</code>
template. */
private String artifactId;
- /** The maven version to use in the <code>README.vm</code> template. */
+ /** The Maven version to use in the <code>README.vm</code> template. */
private String version;
- /** The site url to use in the <code>README.vm</code> template. */
+ /** The site URL to use in the <code>README.vm</code> template. */
private String siteUrl;
/**
@@ -65,9 +65,9 @@ public final class ReadmeHtmlVelocityDelegate {
}
/**
- * Adds the artifactId to the {@link ReadmeHtmlVelocityDelegate}.
+ * Sets the Maven artifact ID for the {@link
ReadmeHtmlVelocityDelegate}.
*
- * @param artifactId The {@link String} representing the maven
artifactId.
+ * @param artifactId The {@link String} representing the Maven
artifactId.
* @return The builder to continue building.
*/
public ReadmeHtmlVelocityDelegateBuilder setArtifactId(final String
artifactId) {
@@ -76,9 +76,9 @@ public final class ReadmeHtmlVelocityDelegate {
}
/**
- * Adds the siteUrl to the {@link ReadmeHtmlVelocityDelegate}.
+ * Sets the site URL for the {@link ReadmeHtmlVelocityDelegate}.
*
- * @param siteUrl The site url to be used in the
<code>README.html</code>
+ * @param siteUrl The site URL to be used in the
<code>README.html</code>
* @return The builder to continue building.
*/
public ReadmeHtmlVelocityDelegateBuilder setSiteUrl(final String
siteUrl) {
@@ -87,9 +87,9 @@ public final class ReadmeHtmlVelocityDelegate {
}
/**
- * Adds the version to the {@link ReadmeHtmlVelocityDelegate}.
+ * Sets the version for the {@link ReadmeHtmlVelocityDelegate}.
*
- * @param version The maven version.
+ * @param version The Maven version.
* @return The builder to continue building.
*/
public ReadmeHtmlVelocityDelegateBuilder setVersion(final String
version) {
@@ -103,7 +103,7 @@ public final class ReadmeHtmlVelocityDelegate {
*/
private static final Pattern END_DIGIT = Pattern.compile(".+\\d$");
- /** The location of the velocity template for this class. */
+ /** The location of the Velocity template for this class. */
private static final String TEMPLATE =
"resources/org/apache/commons/release/plugin"
+ "/velocity/README.vm";
@@ -116,13 +116,13 @@ public final class ReadmeHtmlVelocityDelegate {
return new ReadmeHtmlVelocityDelegateBuilder();
}
- /** This is supposed to represent the maven artifactId. */
+ /** This is supposed to represent the Maven artifactId. */
private final String artifactId;
- /** This is supposed to represent the maven version of the release. */
+ /** This is supposed to represent the Maven version of the release. */
private final String version;
- /** The url of the site that gets set into the <code>README.html</code>. */
+ /** The URL of the site that gets set into the <code>README.html</code>. */
private final String siteUrl;
/**
@@ -139,7 +139,7 @@ public final class ReadmeHtmlVelocityDelegate {
}
/**
- * Renders the <code>README.vm</code> velocity template with the variables
constructed with the
+ * Renders the <code>README.vm</code> Velocity template with the variables
constructed with the
* {@link ReadmeHtmlVelocityDelegateBuilder}.
*
* @param writer is the {@link Writer} to which we wish to render the
<code>README.vm</code> template.
diff --git
a/src/main/java/org/apache/commons/release/plugin/velocity/package-info.java
b/src/main/java/org/apache/commons/release/plugin/velocity/package-info.java
index f0684f4..825fd90 100644
--- a/src/main/java/org/apache/commons/release/plugin/velocity/package-info.java
+++ b/src/main/java/org/apache/commons/release/plugin/velocity/package-info.java
@@ -16,10 +16,9 @@
*/
/**
- * Contains classes that take our velocity templates and render's them to a
{@link java.io.Writer}
- * class.
+ * Contains classes that render Velocity templates to a {@link java.io.Writer}.
* <p>
- * The main reason for velocity templates are to fill out the following files
that get deployed alongside:
+ * The Velocity templates generate the following files, which are deployed
alongside the release:</p>
* <ul>
* <li><code>HEADER.html</code></li>
* <li><code>README.html</code></li>
diff --git a/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
b/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
index f09f6db..f0a39a2 100644
--- a/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
+++ b/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
@@ -21,11 +21,11 @@ Subject: [VOTE] Release @NAME@ @VERSION@ based on @RC@
We have fixed a few bugs and added enhancements since the release of @NAME@
@BC@, so I would like to release @NAME@ @VERSION@.
@NAME@ @VERSION@ @RC@ is available for review here:
- @DISTURL@ (svn revision @RCREV@)
+ @DISTURL@ (SVN revision @RCREV@)
The Git tag @TAGNAME@ commit for this RC is @TAGCOMMIT@, which you can browse
here:
https://gitbox.apache.org/repos/asf?p=commons-@[email protected];a=commit;h=@TAGCOMMIT@
-You may checkout this tag using:
+You may check out this tag using:
git clone https://gitbox.apache.org/repos/asf/commons-@[email protected] --branch
@TAGNAME@ @TAGNAME@
Maven artifacts are here:
@@ -98,43 +98,43 @@ You can validate a release from a release candidate (RC)
tag as follows.
@DISTURL@/source
-1b) Check out the RC tag from git (optional)
+1b) Check out the RC tag from Git (optional)
-This is optional, as a reviewer must at least check source distributions.
+This is optional, as a reviewer must at least check source distributions.
git clone https://gitbox.apache.org/repos/asf/commons-@[email protected] --branch
@TAGNAME@ @TAGNAME@
cd @TAGNAME@
-2) Checking the build
+2) Check the build
All components should include a default Maven goal, such that you can run
'mvn' from the command line by itself.
-2) Check Apache licenses
+3) Check Apache licenses
This step is not required if the site includes a RAT report page, which you
then must check.
This check should be included in the default Maven build, but you can check it
with:
mvn apache-rat:check
-3) Check binary compatibility
+4) Check binary compatibility
This step is not required if the site includes a JApiCmp report page, which
you then must check.
This check should be included in the default Maven build, but you can check it
with:
mvn verify -DskipTests -P japicmp japicmp:cmp
-4) Build the package
+5) Build the package
This check should be included in the default Maven build, but you can check it
with:
mvn -V clean package
-You can record the Maven and Java version produced by -V in your VOTE reply.
+You can record the Maven and Java versions produced by -V in your VOTE reply.
To gather OS information from a command line:
Windows: ver
Linux: uname -a
-4b) Check reproducibility
+6) Check reproducibility
To check that a build is reproducible, run:
@@ -144,7 +144,7 @@ mvn clean verify artifact:compare -DskipTests
-Dreference.repo=https://repositor
Note that this excludes SPDX files from the check.
-5) Build the site for a single module project
+7) Build the site for a single-module project
Note: Some plugins require the components to be installed instead of packaged.
@@ -153,7 +153,7 @@ Check the site reports in:
- Windows: target\site\index.html
- Linux: target/site/index.html
-6) Build the site for a multi-module project
+8) Build the site for a multi-module project
mvn site
mvn site:stage
diff --git
a/src/main/resources/org/apache/commons/release/plugin/velocity/README.vm
b/src/main/resources/org/apache/commons/release/plugin/velocity/README.vm
index 20711dc..d581001 100644
--- a/src/main/resources/org/apache/commons/release/plugin/velocity/README.vm
+++ b/src/main/resources/org/apache/commons/release/plugin/velocity/README.vm
@@ -21,8 +21,8 @@
<p><font color="red" size="+2">Note:</font>
The tar files in the distribution use GNU tar extensions
- and must be untarred with a GNU compatible version of tar. The version
- of tar on Solaris and Mac OS X will not work with these files</p>
+ and must be untarred with a GNU-compatible version of tar. The version
+ of tar on Solaris and Mac OS X will not work with these files.</p>
<a name="changes"><h2>Changes</h2></a>
diff --git a/src/main/scripts/generate-xdocs.mojos.xml
b/src/main/scripts/generate-xdocs.mojos.xml
index b349031..e516cc7 100644
--- a/src/main/scripts/generate-xdocs.mojos.xml
+++ b/src/main/scripts/generate-xdocs.mojos.xml
@@ -27,7 +27,7 @@
<mojo>
<goal>vote-txt</goal>
<call>vote-txt</call>
- <description>Apache Commons Release Mojo: Generate VOTE.txt
file.</description>
+ <description>Apache Commons Release Mojo: Generate a VOTE.txt
file.</description>
<requiresProject>true</requiresProject>
<parameters>
<parameter>
@@ -64,7 +64,7 @@
<readonly>false</readonly>
<defaultValue>${commons.jira.id}</defaultValue>
<type>java.lang.String</type>
- <description>The external JIRA id for the project (alphabetic, upper
case.)</description>
+ <description>The external JIRA ID for the project (alphabetic,
uppercase).</description>
</parameter>
<parameter>
<name>commons.componentid</name>
@@ -73,7 +73,7 @@
<readonly>true</readonly>
<defaultValue>${commons.componentid}</defaultValue>
<type>java.lang.String</type>
- <description>The commons component id.</description>
+ <description>The Commons component ID.</description>
</parameter>
<parameter>
<name>commons.jira.pid</name>
@@ -82,7 +82,7 @@
<readonly>false</readonly>
<defaultValue>${commons.jira.pid}</defaultValue>
<type>java.lang.String</type>
- <description>The internal JIRA id for the project
(numeric.)</description>
+ <description>The internal JIRA ID for the project
(numeric).</description>
</parameter>
<parameter>
<name>commons.rc.version</name>
@@ -100,7 +100,7 @@
<readonly>false</readonly>
<defaultValue>${commons.bc.version}</defaultValue>
<type>java.lang.String</type>
- <description>The version of the latest release of the project this
candidate should have binary compatibility.</description>
+ <description>The version of the latest release of the project with
which this candidate should be binary compatible.</description>
</parameter>
<parameter>
<name>commons.release.version</name>
@@ -145,7 +145,7 @@
<readonly>false</readonly>
<defaultValue>${commons.release.subdir}</defaultValue>
<type>java.lang.String</type>
- <description>Subdirectory (instead of source/binaries.)</description>
+ <description>Subdirectory (instead of source/binaries).</description>
</parameter>
<parameter>
<name>commons.releaseManagerName</name>
@@ -172,7 +172,7 @@
<readonly>false</readonly>
<defaultValue>${commons.nexus.repo.id}</defaultValue>
<type>java.lang.String</type>
- <description>The Nexus repository ID on
https://repository.apache.org/, usually a four digit number.
+ <description>The Nexus repository ID on
https://repository.apache.org/, usually a four-digit number.
This is the value after
https://repository.apache.org/content/repositories/orgapachecommons-
</description>
</parameter>
diff --git a/src/site/xdoc/development.xml b/src/site/xdoc/development.xml
index 187e9cd..313d9db 100644
--- a/src/site/xdoc/development.xml
+++ b/src/site/xdoc/development.xml
@@ -36,8 +36,8 @@
<section name="New Mojos">
<p>
- Each Mojo is a java file that extends <code>AbstractMojo</code> that
contains an annotation specifying
- the goal name for the mojo and the maven lifecycle phase that it
executes under by default. For, example
+ Each mojo is a Java class that extends <code>AbstractMojo</code> and
contains an annotation specifying
+ the goal name for the mojo and the Maven lifecycle phase in which it
executes by default. For example, the following class
<source><![CDATA[
package org.apache.commons.release.plugin.mojos;
@@ -45,19 +45,18 @@ package org.apache.commons.release.plugin.mojos;
public class CommonsDistributionDetachmentMojo extends AbstractMojo {
.....
}]]></source>
- specifies the goal <code>commons-release:detach-distributions</code>
that is to occur during the VERIFY maven
- lifecycle.
+ specifies the goal <code>commons-release:detach-distributions</code>
that is to occur during the VERIFY phase of the Maven lifecycle.
</p>
<p>
- The variables in the mojo that are declared as private with the
annotations <code>@Parameter</code> get
- imported to the Mojo by the existent maven variables or the declared
<code><configuration></code>. For
+ The variables in the mojo that are declared as private with the
annotation <code>@Parameter</code> are
+ initialized from existing Maven variables or the declared
<code><configuration></code>. For
example, we have a boolean variable named <code>dryRun</code> declared
as:
<source><![CDATA[
@Parameter(property = "commons.release.dryRun", defaultValue = "false")
private Boolean dryRun;
]]></source>
- that can be configured by
+ that can be configured as follows:
<source><![CDATA[
<plugin>
<groupId>org.apache.commons</groupId>
@@ -68,8 +67,8 @@ private Boolean dryRun;
</configuration>
</plugin>]]></source>
- And, because we've set the <code>property here</code> (as in the 1.1
release), you can, on the command line,
- use the following <code>-Dcommons.release.dryRun=true</code>.
+ Because we've set the <code>property</code> here (as in the 1.1
release), you can use
+ <code>-Dcommons.release.dryRun=true</code> on the command line.
</p>
</section>
@@ -77,12 +76,12 @@ private Boolean dryRun;
<section name="Unit testing">
<p>
- We've declared mock maven poms in the <code>resources</code> directory
of the <code>src/test</code> folder,
- under which we've stored in subdirectories corresponding to the names
of the mojos that they are testing. All
- variables that you wish to be available to your mojo must be
specifically declared in the mock pom file. For
- example, we need to use the already existent <code>MavenProject</code>
in the maven runtime by instead, in a
- test package declaring a class extending <code>MavenProjectStub</code>
that returns values we wish to be used
- in testing. We then add this to our pom in the following declaration
of the plugin:
+ We've declared mock Maven POMs in the <code>resources</code> directory
of the <code>src/test</code> folder,
+ stored in subdirectories corresponding to the names of the mojos that
they are testing. All
+ variables that you wish to be available to your mojo must be
specifically declared in the mock POM file. For
+ example, we can supply a <code>MavenProject</code> to the Maven
runtime by declaring a class in a
+ test package that extends <code>MavenProjectStub</code> and returns
the values we wish to use
+ in testing. We then add this to our POM in the following declaration
of the plugin:
<source><![CDATA[
<plugin>
<groupId>org.apache.commons</groupId>
@@ -93,7 +92,7 @@ private Boolean dryRun;
<distSvnStagingUrl>mockDistSvnStagingUrl</distSvnStagingUrl>
</configuration>
</plugin>]]></source>
- Also note here we are declaring other values that we are using in the
testing of the plugin. We then retrieve
+ Also note that we are declaring other values that we are using in the
testing of the plugin. We then retrieve
our instantiated mojo by declaring a <code>MojoRule</code> in our test
class,
<source><![CDATA[
@Rule
@@ -106,7 +105,7 @@ public MojoRule rule = new MojoRule() {
protected void after() {
}
};]]></source>
- and then retrieve the mojo by newing up a <code>File</code> pointed to
the path of the mock pom, and then
+ and then retrieve the mojo by creating a <code>File</code> pointing to
the mock POM and then
making the following call:
<source><![CDATA[
mojo = (CommonsSiteCompressionMojo) rule.lookupMojo("compress-site", testPom);
@@ -120,12 +119,12 @@ mojo = (CommonsSiteCompressionMojo)
rule.lookupMojo("compress-site", testPom);
<p>
Maven ships with a debugger under the hood. It is suggested that you
have a sandbox project in which you can
- run the goals or the plugin configuration. Once you have that set up
you can run something like
+ run the goals or the plugin configuration. Once you have that set up,
you can run something like
<source><![CDATA[
mvnDebug commons-release:detach-distributions
]]></source>
- which exposes a remote debugger on port 8000 and halts the maven
process until you attach a remote debugger
- to that port. Once you have a remote debugger attached the maven
process continues and stops at any
+ which exposes a remote debugger on port 8000 and halts the Maven
process until you attach a remote debugger
+ to that port. Once you have a remote debugger attached, the Maven
process continues and stops at any
breakpoints that you have set up in your project.
</p>
diff --git a/src/site/xdoc/download_release-plugin.xml
b/src/site/xdoc/download_release-plugin.xml
index d038933..bb93add 100644
--- a/src/site/xdoc/download_release-plugin.xml
+++ b/src/site/xdoc/download_release-plugin.xml
@@ -106,7 +106,7 @@ limitations under the License.
It is essential that you
<a href="https://www.apache.org/info/verification.html";>verify the
integrity</a>
of downloaded files, preferably using the <code>PGP</code> signature
(<code>*.asc</code> files);
- failing that using the <code>SHA512</code> hash (<code>*.sha512</code>
checksum files).
+ failing that, using the <code>SHA512</code> hash
(<code>*.sha512</code> checksum files).
</p>
<p>
The <a href="https://downloads.apache.org/commons/KEYS";>KEYS</a>
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index ed9ce8d..53fe098 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -28,40 +28,39 @@
<section name="Release Plugin">
<p>
- This is a <a href="https://maven.apache.org/";>Maven 3.x</a> Plugin
which is
- used by <a href="https://commons.apache.org/";>Apache Commons</a>
releases. See
+ This is a <a href="https://maven.apache.org/";>Maven 3.x</a> plugin
that is
+ used for <a href="https://commons.apache.org/";>Apache Commons</a>
releases. See
the <a href="development.html">Development</a> page for
information to
help maintain this plugin.
</p>
- <p>The main purpose of the plugin is to automate the steps of our,
namely
- The Apache Commons Project's, release process. Currently we have
the mechanics
- for detaching distribution artifacts (i.e. all <code>tar.gz</code>
artifacts and
+ <p>The main purpose of the plugin is to automate the steps of the
+ Apache Commons Project's release process. Currently, it supports
detaching distribution artifacts (i.e., all <code>tar.gz</code> artifacts and
signatures as well as all <code>.zip</code> artifacts and
signatures), creating
- a <code>site.zip</code> file, and staging all of those artifacts
in a subversion
+ a <code>site.zip</code> file, and staging all of those artifacts
in a Subversion
repository (for the most part a subdirectory of
- <a
href="https://dist.apache.org/repos/dist/dev/commons/";>https://dist.apache.org/repos/dist/dev/commons/</a>.
- It can, however, stage to any subversion repository.
+ <a
href="https://dist.apache.org/repos/dist/dev/commons/";>https://dist.apache.org/repos/dist/dev/commons/</a>).
+ It can, however, stage to any Subversion repository.
</p>
</section>
<section name="Plugin Goals">
<p>
- Available Goals (which are meant to be used together; the only
reason they are separated is for
+ Available goals (which are meant to be used together; the only
reason they are separated is for
code readability):
</p>
<ul>
<li>
<b>commons-release:detach-distributions</b> - Remove
<code>tar.gz</code>, <code>tar.gz.asc</code>,
<code>zip</code>, and <code>zip.asc</code>
- files from being uploaded to nexus and copy them to the
<code>target/commons-release-plugin</code>
+ files from being uploaded to Nexus and copy them to the
<code>target/commons-release-plugin</code>
directory.
</li>
<li>
<b>commons-release:stage-distributions</b> - Take all
staged files in the
<code>target/commons-release-plugin</code> directory, and
the <code>RELEASE-NOTES.txt</code> from
- the root of the project, and commit them to a specified
staging subversion repository.
+ the root of the project, and commit them to a specified
staging Subversion repository.
</li>
<li>
<a href="vote-txt.html">commons-release:vote-txt</a>
-Dcommons.nexus.repo.id=nnnn [-Dgit.tag.name] # where nnn is the number
following orgapachecommons- in the Nexus 'Repository' column
@@ -71,9 +70,9 @@
<section name="Using the plugin">
<p>
- Configure the plugin as the last plugin in
the<code><build></code> section of the <code>pom.xml</code>
+ Configure the plugin as the last plugin in the
<code><build></code> section of the <code>pom.xml</code> file.
</p>
- <p>This is now done in the Commons Parent POM, so is not needed in
the component POM.</p>
+ <p>This is now done in the Commons Parent POM, so it is not needed
in the component POM.</p>
<source><![CDATA[
<plugin>
<groupId>org.apache.commons</groupId>
@@ -105,7 +104,7 @@
</plugin>
]]></source>
<p>
- The following properties need to be defined in the component POM
if not already defined
+ The following properties need to be defined in the component POM
if they are not already defined:
</p>
<source><![CDATA[
<properties>
@@ -116,7 +115,7 @@
]]></source>
<p>
Ensure your Release Manager details are defined in your Maven
<code>~/.m2/settings.xml</code> file
- (These are used by the vote-txt goal)
+ (these are used by the vote-txt goal).
Properties have to be defined in a profile. For example:
</p>
<source><![CDATA[
@@ -141,17 +140,17 @@
</settings>
]]></source>
<p>
- After the above configuration performing the release would occur
by (<i>note.</i> more
- in depth details can be found at
+ After configuring the plugin as shown above, perform the release
using the following steps (more
+ in-depth details can be found at
<a
href="https://commons.apache.org/releases/prepare.html";>Preparations For A
Release</a>):
</p>
<ol>
<li>creating our release branch,</li>
<li>checking compatibility,</li>
<li>checking your dependencies,</li>
- <li>checking javadocs and code style,</li>
- <li>checking the apache license,</li>
- <li>configure the build to generate a complete set of release
artifacts,</li>
+ <li>checking Javadocs and code style,</li>
+ <li>checking the Apache license,</li>
+ <li>configuring the build to generate a complete set of release
artifacts,</li>
<li>preparing the release notes, updating the download file and
other autogenerated files,</li>
<li>tagging the release candidate, and</li>
<li>
@@ -166,9 +165,9 @@ mvn -Duser.name=<yourApacheId>
[-Duser.password=<yourApacheIdsPassword] [-Dcommo
to specify a server definition in Maven <code>settings.xml</code>
which defines your (encrypted, right?) authentication info.
</p>
<p>
- 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
+ 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>. Note
+ that to perform a dry run of the release, you need to include
<code>-Dcommons.release.dryRun=true -Ptest-deploy</code>.
</p>
</section>
diff --git a/src/site/xdoc/issue-tracking.xml b/src/site/xdoc/issue-tracking.xml
index 57d9d88..af754a6 100644
--- a/src/site/xdoc/issue-tracking.xml
+++ b/src/site/xdoc/issue-tracking.xml
@@ -57,19 +57,19 @@ limitations under the License.
</p>
<p>
- To use JIRA you may need to <a
href="https://issues.apache.org/jira/secure/Signup!default.jspa";>create an
account</a>
- (if you have previously created/updated Commons issues using Bugzilla an
account will have been automatically
+ To use JIRA, you may need to <a
href="https://issues.apache.org/jira/secure/Signup!default.jspa";>create an
account</a>
+ (if you have previously created/updated Commons issues using Bugzilla,
an account will have been automatically
created and you can use the <a
href="https://issues.apache.org/jira/secure/ForgotPassword!default.jspa";>Forgot
Password</a>
page to get a new password).
</p>
<p>
If you would like to report a bug, or raise an enhancement request with
- Apache Commons Release Plugin please do the following:
+ Apache Commons Release Plugin, please do the following:
</p>
<ol>
<li><a
href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&pid=12310466&component=12312401&sorter/field=issuekey&sorter/order=DESC&status=1&status=3&status=4";>Search
existing open bugs</a>.
- If you find your issue listed then please add a comment with your
details.</li>
+ If you find your issue listed, please add a comment with your
details.</li>
<li><a href="mail-lists.html">Search the mailing list archive(s)</a>.
You may find your issue or idea has already been discussed.</li>
<li>Decide if your issue is a bug or an enhancement.</li>
@@ -87,7 +87,7 @@ limitations under the License.
</ul>
<p>
- For more information on creating patches see the
+ For more information on creating patches, see the
<a href="https://www.apache.org/dev/contributors.html";>Apache
Contributors Guide</a>.
</p>
diff --git a/src/site/xdoc/mail-lists.xml b/src/site/xdoc/mail-lists.xml
index 053ca82..eb4630c 100644
--- a/src/site/xdoc/mail-lists.xml
+++ b/src/site/xdoc/mail-lists.xml
@@ -72,7 +72,7 @@ limitations under the License.
to subscribe.
</p>
<p>
- <strong>Note:</strong> please don't send patches or attachments to any
of the mailing lists;
+ <strong>Note:</strong> Please don't send patches or attachments to any
of the mailing lists;
most of the lists are set up to drop attachments.
Patches are best handled via the <a href="issue-tracking.html">Issue
Tracking</a> system.
If you have a GitHub account, most components also accept PRs (pull
requests).
diff --git a/src/site/xdoc/vote-txt.xml b/src/site/xdoc/vote-txt.xml
index 4ec61ff..8e5e0ac 100644
--- a/src/site/xdoc/vote-txt.xml
+++ b/src/site/xdoc/vote-txt.xml
@@ -30,17 +30,17 @@
Execute the goal using the following command: <source>mvn
commons-release:vote-txt</source>
</p>
<p>
- <strong>Note:</strong> The VOTE.txt should be regenerated
before every release candidate.
+ <strong>Note:</strong> The VOTE.txt file should be regenerated
before every release candidate.
</p>
<p>
- This goal uses the following:
+ This goal works as follows:
</p>
<ul>
- <li>The goal is mapped to the ant script/target using the
<code>vote-txt</code> mojo definition in the
+ <li>The goal is mapped to the Ant script/target using the
<code>vote-txt</code> mojo definition in the
<a
href="https://svn.apache.org/repos/asf/commons/proper/commons-release-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml";>generate-xdocs.mojos.xml</a>
mapping document</li>
- <li>Executes the <code>vote-txt</code> target in
+ <li>Executes the <code>vote-txt</code> target in the
<a
href="https://svn.apache.org/repos/asf/commons/proper/commons-release-plugin/trunk/src/main/scripts/generate-xdocs.build.xml";>generate-xdocs.build.xml</a>
- ant script</li>
+ Ant script</li>
<li>Uses the <a
href="https://svn.apache.org/repos/asf/commons/proper/commons-release-plugin/trunk/src/main/resources/commons-xdoc-templates/vote-txt-template.md";>vote-txt-template.md</a>
template</li>
<li>Uses the <a href="vote-txt-mojo.html">goal's (i.e.
mojo's) parameters</a> to filter values in the template</li>
@@ -48,7 +48,7 @@
</subsection>
<subsection name="Configuration">
<p>
- To generate a VOTE.txt, the following <a
href="vote-txt-mojo.html">properties</a> are configured in the component's
<code>pom.xml</code>
+ To generate a VOTE.txt file, configure the following <a
href="vote-txt-mojo.html">properties</a> in the component's
<code>pom.xml</code>:
</p>
<ul>
<li><b>commons.componentid</b> - Commons component ID</li>
diff --git
a/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java
b/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java
index 7565452..010e63d 100644
--- a/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java
+++ b/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java
@@ -16,10 +16,10 @@
*/
/**
- * This package is meant to contain stubbed objects for the maven testing
- * paradigm. These stubs can in turn be used in the poms in the
<code>src/test/resources</code>
+ * This package is meant to contain stubbed objects for the Maven testing
+ * paradigm. These stubs can in turn be used in the POMs in the
<code>src/test/resources</code>
* directory of the project in the implementation block of the declaration of
the configuration
- * property. The maven unit testing framework then wires this stubbed object
into the appropriate mojo
+ * property. The Maven unit testing framework then wires this stubbed object
into the appropriate mojo
* for testing purposes.
*
* @since 1.0
