This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-atr-plugin
in repository https://gitbox.apache.org/repos/asf/maven-studies.git
The following commit(s) were added to refs/heads/maven-atr-plugin by this push:
new 574c2c6e7 add documentation
574c2c6e7 is described below
commit 574c2c6e7b101271776fb69a9035a447c5c4a6a3
Author: Hervé Boutemy <[email protected]>
AuthorDate: Sun Mar 15 17:07:30 2026 +0100
add documentation
---
.../org/apache/maven/plugins/atr/AtrClient.java | 8 +-
.../org/apache/maven/plugins/atr/UploadMojo.java | 6 +-
src/site/markdown/index.md | 44 ++++++++
src/site/markdown/usage.md | 122 +++++++++++++++++++++
src/site/site.xml | 35 ++++++
5 files changed, 206 insertions(+), 9 deletions(-)
diff --git a/src/main/java/org/apache/maven/plugins/atr/AtrClient.java
b/src/main/java/org/apache/maven/plugins/atr/AtrClient.java
index 59e1cb5af..31d4bc745 100644
--- a/src/main/java/org/apache/maven/plugins/atr/AtrClient.java
+++ b/src/main/java/org/apache/maven/plugins/atr/AtrClient.java
@@ -105,14 +105,14 @@ public class AtrClient {
/**
* Upload a file to ATR.
*
- * @param project the project name
+ * @param project the project id
* @param version the version
- * @param relpath the relative path within the release (e.g.,
"artifactId-version-source-release.zip")
+ * @param path the relative path within the release (e.g.,
"artifactId-version-source-release.zip")
* @param file the file to upload
* @return the revision number
* @throws MojoExecutionException if the upload fails
*/
- public String uploadFile(String project, String version, String relpath,
Path file) throws MojoExecutionException {
+ public String uploadFile(String project, String version, String path, Path
file) throws MojoExecutionException {
// Ensure we have a valid JWT
ensureJwt();
@@ -122,7 +122,7 @@ public class AtrClient {
String content = Base64.getEncoder().encodeToString(fileBytes);
// Create upload request
- ReleaseUploadRequest request = new ReleaseUploadRequest(project,
version, relpath, content);
+ ReleaseUploadRequest request = new ReleaseUploadRequest(project,
version, path, content);
// Create connection
URL uploadUrl = new URL(baseUrl, "api/release/upload");
diff --git a/src/main/java/org/apache/maven/plugins/atr/UploadMojo.java
b/src/main/java/org/apache/maven/plugins/atr/UploadMojo.java
index 225829011..0b81f239b 100644
--- a/src/main/java/org/apache/maven/plugins/atr/UploadMojo.java
+++ b/src/main/java/org/apache/maven/plugins/atr/UploadMojo.java
@@ -35,7 +35,7 @@ import org.apache.maven.plugins.annotations.Parameter;
public class UploadMojo extends AbstractAtrMojo {
/**
- * The project name for ATR upload.
+ * The project id for ATR upload.
*/
@Parameter(property = "atr.project", required = true)
private String project;
@@ -54,7 +54,6 @@ public class UploadMojo extends AbstractAtrMojo {
/**
* The target directory in ATR upload area where files will be uploaded.
- * If not specified, files will be uploaded to the default location.
*/
@Parameter(property = "atr.directory")
private String directory;
@@ -67,9 +66,6 @@ public class UploadMojo extends AbstractAtrMojo {
getLog().info("Uploading artifacts to ATR...");
}
getLog().info("Composing release " + url + "compose/" + project + "/"
+ version);
- if (directory != null) {
- getLog().info("Directory: " + directory);
- }
getLog().info("Files: " + files.length);
for (Path file : files) {
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 000000000..ec8764ed7
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,44 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Apache Maven ATR Plugin
+
+The Maven ATR Plugin is used to upload Apache release artifacts to [ATR
(Apache Trusted Releases)][introduction-to-atr] before starting a vote.
+
+## Goals Overview
+
+The ATR Plugin has one goal:
+
+* [atr:upload](./upload-mojo.html) uploads distribution artifacts to ATR
compose space.
+
+## Usage
+
+General instructions on how to use the Maven ATR Plugin can be found on the
[usage page](./usage.html).
+
+In case you still have questions regarding the plugin's usage, please feel
free to contact the [user mailing list](./mailing-lists.html). The posts to the
mailing list are archived and could already contain the answer to your question
as part of an older thread. Hence, it is also worth browsing/searching the
[mail archive](./mailing-lists.html).
+
+If you feel like the plugin is missing a feature or has a bug, you can fill a
feature request or bug report in our [issue tracker](./issue-management.html).
When creating a new issue, please provide a comprehensive description of your
concern. Especially for fixing bugs it is crucial that the developers can
reproduce your problem. For this reason, entire debug logs, POMs or most
preferably little demo projects attached to the issue are very much appreciated.
+
+Of course, patches are welcome, too. Contributors can check out the project
from our [source repository](./scm.html) and will find supplementary
information in the [guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html).
+
+## What is ATR?
+
+[ATR (Apache Trusted Releases)][introduction-to-atr] is a platform through
which committees of Apache Software Foundation (ASF) projects can make official
ASF software releases.
+
+[introduction-to-atr]: https://release-test.apache.org/docs/introduction-to-atr
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
new file mode 100644
index 000000000..f40f548fa
--- /dev/null
+++ b/src/site/markdown/usage.md
@@ -0,0 +1,122 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Usage
+
+## Configuring Credentials
+
+The Maven ATR Plugin uses Maven's standard authentication mechanism. Configure
your ATR credentials in `~/.m2/settings.xml`:
+
+```xml
+<settings>
+ <servers>
+ <server>
+ <id>apache.atr</id>
+ <username>your-asf-id</username>
+ <password>your-personal-access-token</password>
+ </server>
+ </servers>
+</settings>
+```
+
+The username should be your ASF user ID and the password should be your
Personal Access Token (PAT) from the ATR service.
+
+For security, you can encrypt your password using [Maven's password
encryption](https://maven.apache.org/guides/mini/guide-encryption.html).
+
+## Basic Upload
+
+To upload release artifacts to ATR:
+
+```
+mvn org.apache.maven.plugins:maven-atr-plugin:upload \
+ -Datr.project=maven \
+ -Datr.version=4.0.0 \
+
-Datr.files=apache-maven-4.0.0-src.tar.gz,apache-maven-4.0.0-src.tar.gz.sha512
+```
+
+## Integration with Release Profile
+
+The typical use case is to integrate the ATR plugin into your `apache-release`
profile:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-atr-plugin</artifactId>
+ <version>1.0.0-beta-1-SNAPSHOT</version>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>apache-release</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-atr-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>upload-to-atr</id>
+ <goals>
+ <goal>upload</goal>
+ </goals>
+ <configuration>
+ <project>${project.artifactId}</project>
+ <version>${project.version}</version>
+ <files>
+
<file>${project.build.directory}/${project.artifactId}-${project.version}-source-release.zip</file>
+
<file>${project.build.directory}/${project.artifactId}-${project.version}-source-release.zip.sha512</file>
+
<file>${project.build.directory}/${project.artifactId}-${project.version}-source-release.zip.asc</file>
+ </files>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+</project>
+```
+
+Then during the release process:
+
+```
+mvn clean deploy -Papache-release
+```
+
+## Directory Organization
+
+You can organize uploaded files in subdirectories:
+
+```xml
+<configuration>
+ <directory>binaries</directory>
+ <files>
+
<file>${project.build.directory}/${project.artifactId}-${project.version}-bin.tar.gz</file>
+ </files>
+</configuration>
+```
+
+This will upload the file to the compose space at: `binaries/`.
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 000000000..df0a98ffb
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<project xmlns="http://maven.apache.org/DECORATION/1.8.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0
http://maven.apache.org/xsd/decoration-1.8.0.xsd";
+ name="Maven ATR Plugin">
+
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html"/>
+ <item name="Goals" href="plugin-info.html">
+ <item name="atr:upload" href="upload-mojo.html"/>
+ </item>
+ <item name="Usage" href="usage.html"/>
+ </menu>
+
+ <menu ref="reports"/>
+ </body>
+</project>
