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 f0f3a20 Clean up comments for spelling, grammar, and readability
f0f3a20 is described below
commit f0f3a20dfd4facb95a8cb93f24096dd206545e57
Author: Gary Gregory <[email protected]>
AuthorDate: Fri Oct 30 07:30:54 2026 -0400
Clean up comments for spelling, grammar, and readability
Paragraph tags on their own lines.
---
CONTRIBUTING.md | 2 +-
RELEASE-NOTES.txt | 2 +-
src/changes/changes.xml | 2 +-
.../commons/release/plugin/SharedFunctions.java | 21 +++++++------
.../mojos/CommonsDistributionDetachmentMojo.java | 17 +++++------
.../mojos/CommonsDistributionStagingMojo.java | 10 +++----
.../plugin/mojos/CommonsSiteCompressionMojo.java | 7 ++---
.../release/plugin/slsa/v1_2/BuildDefinition.java | 19 +++++++-----
.../release/plugin/slsa/v1_2/DsseEnvelope.java | 4 ++-
.../release/plugin/slsa/v1_2/Provenance.java | 10 +++++--
.../plugin/slsa/v1_2/ResourceDescriptor.java | 10 +++++--
.../release/plugin/slsa/v1_2/RunDetails.java | 4 ++-
.../release/plugin/slsa/v1_2/Signature.java | 4 ++-
.../release/plugin/slsa/v1_2/Statement.java | 10 +++++--
.../release/plugin/slsa/v1_2/package-info.java | 12 +++++---
.../velocity/HeaderHtmlVelocityDelegate.java | 9 +++---
.../velocity/ReadmeHtmlVelocityDelegate.java | 3 +-
.../release/plugin/velocity/package-info.java | 3 +-
.../commons-xdoc-templates/vote-txt-template.txt | 4 +--
.../commons/release/plugin/velocity/README.vm | 34 +++++++++++++++-------
src/main/resources/signature-validator.sh | 12 ++++----
src/site/xdoc/index.xml | 13 +++++----
src/site/xdoc/vote-txt.xml | 2 +-
.../mojos/CommonsStagingCleanupMojoTest.java | 2 +-
.../stubs/DistributionDetachmentProjectStub.java | 10 +++----
25 files changed, 131 insertions(+), 95 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 22c3fb9..0dadfb1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -61,7 +61,7 @@ Making Changes
+ Create a _topic branch_ for your isolated work.
* 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`.
+ * A good topic branch name can be the JIRA bug ID plus a keyword, for
example, `COMMONSSITE-123-InputStream`.
* If you have submitted multiple JIRA issues, try to maintain separate
branches and pull requests.
+ Make commits of logical units.
* Make sure your commit messages are meaningful and in the proper format.
Your commit message should contain the key of the JIRA issue.
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 4caa036..78eed16 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -543,7 +543,7 @@ New Features
------------
o COMMONSSITE-96: Create commons-release-component project skeleton.
-o COMMONSSITE-99: Prepare Standard Build integrations, travis, jacoco,
checkstyle, etc.
+o COMMONSSITE-99: Prepare standard build integrations, including Travis,
JaCoCo, and Checkstyle.
o COMMONSSITE-97: Documentation for commons-release-plugin.
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index be0a768..24d9cba 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -230,7 +230,7 @@
</release>
<release version="1.0" date="2018-01-10" description="Initial release">
<action issue="COMMONSSITE-96" type="add" dev="chtompki">Create
commons-release-component project skeleton.</action>
- <action issue="COMMONSSITE-99" type="add" dev="chtompki">Prepare
Standard Build integrations, travis, jacoco, checkstyle, etc.</action>
+ <action issue="COMMONSSITE-99" type="add" dev="chtompki">Prepare
standard build integrations, including Travis, JaCoCo, and Checkstyle.</action>
<action issue="COMMONSSITE-97" type="add" dev="chtompki">Documentation
for commons-release-plugin</action>
</release>
</body>
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 1ebfc66..b5783e5 100644
--- a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
+++ b/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java
@@ -39,8 +39,7 @@ import org.codehaus.plexus.util.FileUtils;
public final class SharedFunctions {
/**
- * I want a buffer that is an array with 1024 elements of bytes. We declare
- * the constant here for the sake of making the code more readable.
+ * The buffer size in bytes.
*/
public static final int BUFFER_BYTE_SIZE = 1024;
@@ -51,7 +50,7 @@ public final class SharedFunctions {
* @param log The {@link Log}, the Maven logger.
* @param fromFile The {@link File} from which to copy.
* @param toFile The destination {@link File}.
- * @throws MojoExecutionException Thrown if an {@link IOException} or
{@link NullPointerException} is caught.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
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";
@@ -72,7 +71,7 @@ public final class SharedFunctions {
*
* @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.
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
public static void initDirectory(final Log log, final File
workingDirectory) throws MojoExecutionException {
final String format = "Unable to remove directory %s: %s";
@@ -166,12 +165,12 @@ public final class SharedFunctions {
/**
* Sets authentication information on the specified {@link
ScmProviderRepository}.
*
- * @param providerRepository target.
- * @param distServer temp.
- * @param settings temp.
- * @param settingsDecrypter temp.
- * @param username temp.
- * @param password temp.
+ * @param providerRepository The repository to configure.
+ * @param distServer The server ID used to look up credentials in Maven
settings.
+ * @param settings The Maven settings.
+ * @param settingsDecrypter The decrypter for stored credentials.
+ * @param username The fallback username when no server username is
available.
+ * @param password The fallback password when no server password is
available.
*/
public static void setAuthentication(final ScmProviderRepository
providerRepository,
final String distServer,
@@ -191,6 +190,6 @@ public final class SharedFunctions {
* Prevents instantiation of this utility class.
*/
private SharedFunctions() {
- // Utility Class
+ // 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 a9ebd6f..ff38449 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
@@ -79,14 +79,12 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
private final List<Artifact> detachedArtifacts = new ArrayList<>();
/**
- * A {@link SortedProperties} of {@link Artifact} → {@link String}
containing the sha512 signatures
- * for the individual artifacts, where the {@link Artifact} is represented
as:
- * <code>groupId:artifactId:version:type=sha512</code>.
+ * A {@link SortedProperties} mapping artifact file names to their SHA-512
hashes.
*/
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 access the project
variables.
*/
@Parameter(defaultValue = "${project}", required = true)
private MavenProject project;
@@ -199,7 +197,7 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * Gets the file path for the <code>sha512</code> signature file for a
given file.
+ * Gets the file path for the <code>sha512</code> checksum 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.
@@ -214,9 +212,8 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * A helper method that creates sha512 signature files for our detached
artifacts in the
- * <code>target/commons-release-plugin</code> directory for the purpose
of being uploaded by
- * the {@link CommonsDistributionStagingMojo}.
+ * Creates SHA-512 checksum files for detached artifacts in the
<code>target/commons-release-plugin</code> directory
+ * for upload by {@link CommonsDistributionStagingMojo}.
*
* @throws MojoExecutionException Thrown if an {@link IOException} occurs.
*/
@@ -241,10 +238,10 @@ public final class CommonsDistributionDetachmentMojo
extends AbstractMojo {
}
/**
- * Takes an attached artifact and puts the signature in the map.
+ * Computes the SHA-512 hash of an attached artifact and stores it in the
map.
*
* @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
+ * @throws MojoExecutionException Thrown if an {@link IOException} occurs
when computing the SHA-512 hash of the
* artifact.
*/
private void putAttachedArtifactInSha512Map(final Artifact artifact)
throws MojoExecutionException {
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 d34f5cf..dc0a115 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
@@ -311,7 +311,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
filesForMavenScmFileSet.add(file);
} else if (Strings.CS.containsAny(file.getName(), "scm",
"sha256.properties", "sha512.properties")) {
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
+ // Do nothing because we are copying into the SCM directory.
} else {
copy = new File(distCheckoutDirectory.getAbsolutePath(),
file.getName());
SharedFunctions.copyFile(getLog(), file, copy);
@@ -354,11 +354,9 @@ public final 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}.
+ * Copies the configured release notes file into {@link
#distRcVersionDirectory}.
*
- * @return The RELEASE-NOTES.txt file that exists in the
<code>target/commons-release-notes/scm</code>
- * directory for the purpose of adding it to the scm change set in
the method
+ * @return The copied release notes file in {@link
#distRcVersionDirectory}, for inclusion in the SCM change set in the method
* {@link
CommonsDistributionStagingMojo#copyDistributionsIntoScmDirectoryStructureAndAddToSvn(File,
* ScmProvider, ScmRepository)}.
* @throws MojoExecutionException Thrown if an {@link IOException} occurs
while copying the file.
@@ -381,7 +379,7 @@ public final class CommonsDistributionStagingMojo extends
AbstractMojo {
private File copySignatureValidatorScriptToScmDirectory() throws
MojoExecutionException {
final Path scmTargetPath =
Paths.get(distRcVersionDirectory.toString(), SIGNATURE_VALIDATOR_NAME);
final String name = "/resources/" + SIGNATURE_VALIDATOR_NAME;
- // The source can be in a local file or inside a jar file.
+ // The source can be in a local file or inside a JAR file.
try {
PathUtils.copyFile(getClass().getResource(name), scmTargetPath);
} catch (final Exception e) {
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 9468636..d8f7031 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
@@ -92,7 +92,7 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
}
/**
- * Given the <code>directoryToZip</code>, we add the <code>file</code> to
the ZIP archive represented by
+ * Adds the <code>file</code> from <code>directoryToZip</code> to the ZIP
archive represented by
* <code>zos</code>.
*
* @param directoryToZip A {@link File} representing the directory
containing the file to compress. Generally, this is <code>target/site</code>.
@@ -102,8 +102,7 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
*/
private void addToZip(final File directoryToZip, final File file, final
ZipOutputStream zos) throws IOException {
try (InputStream fis = Files.newInputStream(file.toPath())) {
- // we want the zipEntry's path to be a relative path that is
relative
- // to the directory being zipped, so chop off the rest of the path
+ // Make the ZIP entry path relative to the directory being
compressed.
final String zipFilePath = file.getCanonicalPath().substring(
directoryToZip.getCanonicalPath().length() + 1,
file.getCanonicalPath().length());
@@ -165,7 +164,7 @@ public final class CommonsSiteCompressionMojo extends
AbstractMojo {
}
/**
- * A helper method for writing all the files in our <code>fileList</code>
to a <code>site.zip</code> file
+ * Writes all the files in <code>fileList</code> to a
<code>site.zip</code> file
* in the <code>workingDirectory</code>.
*
* @param outputDirectory is a {@link File} representing the place to put
the site.zip file.
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/BuildDefinition.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/BuildDefinition.java
index c354623..1f78050 100644
---
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/BuildDefinition.java
+++
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/BuildDefinition.java
@@ -26,8 +26,10 @@ import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Inputs that define the build: the build type, external and internal
parameters, and resolved dependencies.
*
- * <p>Specifies everything that influenced the build output. Together with
{@link RunDetails}, it forms the complete
- * {@link Provenance} record.</p>
+ * <p>
+ * Specifies everything that influenced the build output. Together with {@link
RunDetails}, it forms the complete
+ * {@link Provenance} record.
+ * </p>
*
* @see <a href="https://slsa.dev/spec/v1.2";>SLSA v1.2 Specification</a>
* @since 1.10.0
@@ -91,7 +93,9 @@ public class BuildDefinition {
/**
* Gets the URI indicating what type of build was performed.
*
- * <p>Determines the meaning of {@code externalParameters} and {@code
internalParameters}.</p>
+ * <p>
+ * Determines the meaning of {@code externalParameters} and {@code
internalParameters}.
+ * </p>
*
* @return The build type URI.
*/
@@ -109,8 +113,7 @@ public class BuildDefinition {
}
/**
- * Gets the artifacts the build depends on, such as sources, dependencies,
build tools, and base images,
- * specified by URI and digest.
+ * Gets the parameters set by the build platform.
*
* @return The internal parameters map, or {@code null} if not set.
*/
@@ -121,7 +124,9 @@ public class BuildDefinition {
/**
* Gets the materials that influenced the build.
*
- * <p>Considered incomplete unless resolved materials are present.</p>
+ * <p>
+ * The dependency list is considered incomplete unless resolved materials
are present.
+ * </p>
*
* @return The list of resolved dependencies, or {@code null} if not set.
*/
@@ -157,7 +162,7 @@ public class BuildDefinition {
}
/**
- * Sets the artifacts the build depends on.
+ * Sets the parameters set by the build platform.
*
* @param internalParameters The internal parameters map.
* @return this for chaining.
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 685cb57..3fbc8bc 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,9 @@ 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/Provenance.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Provenance.java
index 5297898..5bb7f63 100644
--- a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Provenance.java
+++ b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Provenance.java
@@ -24,8 +24,10 @@ import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Root predicate of an SLSA v1.2 provenance attestation, describing what was
built and how.
*
- * <p>Combines a {@link BuildDefinition} (the inputs) with {@link RunDetails}
(the execution context). Intended to be
- * used as the {@code predicate} field of an in-toto {@link Statement}.</p>
+ * <p>
+ * This predicate combines a {@link BuildDefinition} (the inputs) with {@link
RunDetails} (the execution context). It is intended to be
+ * used as the {@code predicate} field of an in-toto {@link Statement}.
+ * </p>
*
* @see <a href="https://slsa.dev/spec/v1.2";>SLSA v1.2 Specification</a>
* @since 1.10.0
@@ -74,7 +76,9 @@ public class Provenance {
/**
* Gets the build definition describing all inputs that produced the build
output.
*
- * <p>Includes source code, dependencies, build tools, base images, and
other materials.</p>
+ * <p>
+ * Includes source code, dependencies, build tools, base images, and other
materials.
+ * </p>
*
* @return The build definition, or {@code null} if not set.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/ResourceDescriptor.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/ResourceDescriptor.java
index b710802..37dfc7b 100644
---
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/ResourceDescriptor.java
+++
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/ResourceDescriptor.java
@@ -25,7 +25,9 @@ import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Description of an artifact or resource referenced in the build, identified
by URI and cryptographic digest.
*
- * <p>Used to represent inputs to, outputs from, or byproducts of the build
process.</p>
+ * <p>
+ * Used to represent inputs to, outputs from, or byproducts of the build
process.
+ * </p>
*
* @see <a href="https://slsa.dev/spec/v1.2";>SLSA v1.2 Specification</a>
* @since 1.10.0
@@ -103,7 +105,9 @@ public class ResourceDescriptor {
/**
* Gets the map of cryptographic digest algorithms to their corresponding
hex-encoded values for this resource.
*
- * <p>Common keys include {@code "sha256"} and {@code "sha512"}.</p>
+ * <p>
+ * Common keys include {@code "sha256"} and {@code "sha512"}.
+ * </p>
*
* @return The digest map, or {@code null} if not set.
*/
@@ -121,7 +125,7 @@ public class ResourceDescriptor {
}
/**
- * Gets the media type of the resource (e.g., {@code
"application/octet-stream"}).
+ * Gets the media type of the resource (for example, {@code
"application/octet-stream"}).
*
* @return The media type, or {@code null} if not set.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/RunDetails.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/RunDetails.java
index 8ba4a02..0a01466 100644
--- a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/RunDetails.java
+++ b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/RunDetails.java
@@ -79,7 +79,9 @@ public class RunDetails {
/**
* Gets the builder that executed the invocation.
*
- * <p>Trusted to have correctly performed the operation and populated this
provenance.</p>
+ * <p>
+ * The builder is trusted to have correctly performed the operation and
populated this provenance.
+ * </p>
*
* @return The builder, or {@code null} if not set.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Signature.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Signature.java
index be590f5..49791c0 100644
--- a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Signature.java
+++ b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/Signature.java
@@ -34,7 +34,9 @@ public class Signature {
/**
* Hint for which key was used to sign; unset is treated as empty.
*
- * <p>Consumers MUST NOT require this field to be set, and MUST NOT use it
for security decisions.</p>
+ * <p>
+ * Consumers MUST NOT require this field to be set, and MUST NOT use it
for security decisions.
+ * </p>
*/
@JsonProperty("keyid")
private String keyid;
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 ce91203..92586f9 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
@@ -68,8 +68,10 @@ public class Statement {
/**
* Gets the provenance predicate.
*
- * <p>Unset is treated the same as set-but-empty. May be omitted if {@code
predicateType} fully describes the
- * predicate.</p>
+ * <p>
+ * An unset predicate is treated the same as an empty predicate. The
predicate may be omitted if {@code predicateType} fully describes the
+ * predicate.
+ * </p>
*
* @return The provenance predicate, or {@code null} if not set.
*/
@@ -89,7 +91,9 @@ public class Statement {
/**
* Gets the set of software artifacts that the attestation applies to.
*
- * <p>Each element represents a single artifact. Artifacts are matched
purely by digest, regardless of content type.</p>
+ * <p>
+ * Each element represents a single artifact. Artifacts are matched purely
by digest, regardless of content type.
+ * </p>
*
* @return The list of subject artifacts, or {@code null} if not set.
*/
diff --git
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/package-info.java
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/package-info.java
index 4313f18..1e37f7c 100644
---
a/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/package-info.java
+++
b/src/main/java/org/apache/commons/release/plugin/slsa/v1_2/package-info.java
@@ -18,13 +18,17 @@
/**
* SLSA 1.2 Build Attestation Models.
*
- * <p>This package provides Jackson-annotated model classes that implement the
<a href="https://slsa.dev/spec/v1.2";>Supply-chain Levels for Software Artifacts
- * (SLSA) v1.2 specification</a>.</p>
+ * <p>
+ * This package provides Jackson-annotated model classes that implement the <a
href="https://slsa.dev/spec/v1.2";>Supply-chain Levels for Software Artifacts
+ * (SLSA) v1.2 specification</a>.
+ * </p>
*
* <h2>Overview</h2>
*
- * <p>SLSA is a framework for evaluating and improving the security posture of
build systems. SLSA v1.2 defines a standard for recording build provenance:
- * information about how software artifacts were produced.</p>
+ * <p>
+ * SLSA is a framework for evaluating and improving the security posture of
build systems. SLSA v1.2 defines a standard for recording build provenance:
+ * information about how software artifacts were produced.
+ * </p>
*
* @see <a href="https://slsa.dev/spec/v1.2";>SLSA v1.2 Specification</a>
* @see <a href="https://github.com/in-toto/attestation";>In-toto Attestation
Framework</a>
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 c929350..4ae0565 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,8 +25,7 @@ import org.apache.velocity.runtime.RuntimeConstants;
import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
/**
- * 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.
+ * Generates the <code>HEADER.html</code> file that accompanies the release in
the distribution area.
*
* @since 1.3
*/
@@ -44,9 +43,9 @@ public final class HeaderHtmlVelocityDelegate {
}
/**
- * Builds up the {@link ReadmeHtmlVelocityDelegate} from the
previously set parameters.
+ * Builds a new {@link HeaderHtmlVelocityDelegate}.
*
- * @return A new {@link ReadmeHtmlVelocityDelegate}.
+ * @return A new {@link HeaderHtmlVelocityDelegate}.
*/
public HeaderHtmlVelocityDelegate build() {
return new HeaderHtmlVelocityDelegate();
@@ -57,7 +56,7 @@ public final class HeaderHtmlVelocityDelegate {
private static final String TEMPLATE =
"resources/org/apache/commons/release/plugin/velocity/HEADER.vm";
/**
- * For instantiating our {@link HeaderHtmlVelocityDelegate} using the
{@link HeaderHtmlVelocityDelegateBuilder}.
+ * Gets a builder for constructing a {@link HeaderHtmlVelocityDelegate}.
*
* @return A {@link HeaderHtmlVelocityDelegateBuilder}.
*/
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 ad3273e..d969f9f 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,8 +27,7 @@ import org.apache.velocity.runtime.RuntimeConstants;
import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
/**
- * 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.
+ * Generates the <code>README.html</code> file that accompanies the release in
the distribution area.
*
* @since 1.3
*/
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 825fd90..70a5127 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
@@ -18,7 +18,8 @@
/**
* Contains classes that render Velocity templates to a {@link java.io.Writer}.
* <p>
- * The Velocity templates generate the following files, which are deployed
alongside the release:</p>
+ * 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 f0a39a2..0ff74e9 100644
--- a/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
+++ b/src/main/resources/commons-xdoc-templates/vote-txt-template.txt
@@ -60,8 +60,8 @@ Site:
These exceptions are also noted in the Changes and Release Notes.
Errors reported:
- - methods added to interface: OK because that does not affect binary
compatibility.
- - etc.
+ - methods added to an interface: OK because this does not affect binary
compatibility.
+ - Add other errors and their explanations here.
***
RAT Report:
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 d581001..4d121e7 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
@@ -16,21 +16,31 @@
-->
<h1>${artifactIdWithFirstLetterscapitalized} v${version}.</h1>
-<p>This is the ${version} version of ${artifactId}. It is available in both
binary and source distributions.</p>
+<p>
+This is the ${version} version of ${artifactId}. It is available in both
binary and source distributions.
+</p>
-<p><font color="red" size="+2">Note:</font>
+<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>
+ of tar on Solaris and Mac OS X will not work with these files.
+</p>
<a name="changes"><h2>Changes</h2></a>
-<p>The changes in this release are detailed in the release notes.</p>
+<p>
+The changes in this release are detailed in the release notes.
+</p>
-<p>Thank you for using <a href="${siteUrl}">${artifactShortName}</a>.</p>
+<p>
+Thank you for using <a href="${siteUrl}">${artifactShortName}</a>.
+</p>
-<p>From the Apache Commons Project<br><a
href="https://commons.apache.org/";>https://commons.apache.org/</a></p>
+<p>
+From the Apache Commons Project<br><a
href="https://commons.apache.org/";>https://commons.apache.org/</a>
+</p>
<h2><a name="mirrors">Download from your
<a href="https://www.apache.org/dyn/closer.cgi/commons/";>nearest mirror
site!</a></a></h2>
@@ -44,16 +54,20 @@
<a name="sig"><h2>Signatures</h2></a>
-<p>Many of the files have been digitally signed using GnuPG. If so,
+<p>
+Many of the files have been digitally signed using GnuPG. If so,
there will be an accompanying <samp><em>file</em>.asc</samp> signature
file in the same directory as the file (binaries/ or source/). The
signing keys can be found in the distribution directory at <<a
-
href="https://downloads.apache.org/commons/KEYS";><samp>http://downloads.apache.org/commons/KEYS</samp></a>>.</p>
+
href="https://downloads.apache.org/commons/KEYS";><samp>http://downloads.apache.org/commons/KEYS</samp></a>>.
+</p>
-<p><b>Always download the KEYS file directly from the Apache site, never from
a mirror site.</b></p>
+<p>
+<b>Always download the KEYS file directly from the Apache site, never from a
mirror site.</b>
+</p>
-<pre>Always test available signatures, <i>e.g.</i>,
+<pre>Always test available signatures. For example:
$ pgpk -a KEYS
$ pgpv ${artifactId}-${version}-bin.tar.gz.asc
or,
diff --git a/src/main/resources/signature-validator.sh
b/src/main/resources/signature-validator.sh
index 0352912..3176b87 100755
--- a/src/main/resources/signature-validator.sh
+++ b/src/main/resources/signature-validator.sh
@@ -16,7 +16,7 @@
# limitations under the License.
###########
# DOCUMENTATION.
-# This script is to be placed in the root of the svn dist checkout.
+# Place this script in the root of the SVN distribution checkout.
# For example, my directory looks like:
#
# drwxr-xr-x@ 8 usr staff 256 Oct 1 11:22 .svn
@@ -24,13 +24,13 @@
# -rw-r--r--@ 1 usr staff 2649 Oct 1 11:22 README.html
# -rw-r--r--@ 1 usr staff 5093 Oct 1 11:22 RELEASE-NOTES.txt
# drwxr-xr-x@ 10 usr staff 320 Oct 1 11:22 binaries
-# -rw-r--r--@ 1 usr staff 3900 Oct 1 13:40 signature-validation.sh
+# -rw-r--r--@ 1 usr staff 3900 Oct 1 13:40 signature-validator.sh
# drwxr-xr-x@ 44 usr staff 1408 Oct 1 11:22 site
# drwxr-xr-x@ 10 usr staff 320 Oct 1 11:37 source
#
-# From here you run ./signature-validation.sh and it will create a directory
"artifacts-for-validation-deletable-post-validation
-# in which all of the binaries generated by a release are copied and then it
checks to see that all of the signatures and hashes
-# are infact correct for the artifacts.
+# Run ./signature-validator.sh with the Nexus repository URL as its argument.
The script creates the
+# "artifacts-for-validation-deletable-post-validation" directory and copies
the release artifacts into it
+# for signature and hash validation.
#
###########
@@ -60,7 +60,7 @@ function copy_in_checked_out_artifacts() {
}
function download_nexus_artifacts_to_validation_directory() {
- # Curls html page and does text modification to put artifacts in
semicolon delimited list
+ # Downloads an HTML page and extracts the artifacts into a
semicolon-delimited list.
# ...(ugly but works, debug by removing pipes one at a time)
echo "INFO: Downloading artifacts from nexus"
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index 53fe098..bab356d 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -34,8 +34,9 @@
help maintain this plugin.
</p>
- <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
+ <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 (that is, 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
repository (for the most part a subdirectory of
@@ -63,7 +64,7 @@
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
+ <a href="vote-txt.html">commons-release:vote-txt</a>
-Dcommons.nexus.repo.id=nnnn [-Dgit.tag.name] # where nnnn is the number
following orgapachecommons- in the Nexus 'Repository' column
</li>
</ul>
</section>
@@ -72,7 +73,9 @@
<p>
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 it 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>
@@ -162,7 +165,7 @@ mvn -Duser.name=<yourApacheId>
[-Duser.password=<yourApacheIdsPassword] [-Dcommo
<p>
To avoid specifying distribution credentials at the command
line, consider using the <code>distServer</code> plugin
configuration parameter (property <code>commons.distServer</code>)
- to specify a server definition in Maven <code>settings.xml</code>
which defines your (encrypted, right?) authentication info.
+ to specify a server definition in Maven <code>settings.xml</code>
that defines your encrypted authentication information.
</p>
<p>
If the component is new, then, before running this Maven command,
you would want to create
diff --git a/src/site/xdoc/vote-txt.xml b/src/site/xdoc/vote-txt.xml
index 8e5e0ac..53c3145 100644
--- a/src/site/xdoc/vote-txt.xml
+++ b/src/site/xdoc/vote-txt.xml
@@ -43,7 +43,7 @@
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>
+ <li>Uses the <a href="vote-txt-mojo.html">goal's
parameters</a> to filter values in the template</li>
</ul>
</subsection>
<subsection name="Configuration">
diff --git
a/src/test/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojoTest.java
b/src/test/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojoTest.java
index 391744e..f1fbdf7 100644
---
a/src/test/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojoTest.java
+++
b/src/test/java/org/apache/commons/release/plugin/mojos/CommonsStagingCleanupMojoTest.java
@@ -27,7 +27,7 @@ import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
/**
- * Unit tests for {@link CommonsSiteCompressionMojo}.
+ * Unit tests for {@link CommonsStagingCleanupMojo}.
*/
@MojoTest
public class CommonsStagingCleanupMojoTest {
diff --git
a/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java
b/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java
index 2ecce1e..53cc301 100644
---
a/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java
+++
b/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java
@@ -28,11 +28,11 @@ import
org.apache.maven.plugin.testing.stubs.MavenProjectStub;
import org.apache.maven.project.MavenProject;
/**
- * Stub for {@link MavenProject} for the {@link
CommonsDistributionDetachmentMojoTest}. See the
- * testing pom,
- *
<code>src/test/resources/detach-distributions/detach-distributions.xml</code>
for the declared
- * usage of
- * this class.
+ * Stub for {@link MavenProject} used by {@link
CommonsDistributionDetachmentMojoTest}.
+ *
+ * <p>
+ * See the test POM at
<code>src/test/resources/mojos/detach-distributions/detach-distributions.xml</code>
for the configuration that uses this class.
+ * </p>
*
* @since 1.0
*/
