You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/10/23 19:39:18 UTC
(maven-reporting-api) branch master updated (7964c58 -> 1feb87b)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/maven-reporting-api.git
from 7964c58 Make generate(Sink, Locale) abstract again
new 1d3a6c3 Turn the README into a project page and add contributor, security and agent guides
new 1feb87b Fix the Javadoc wording and describe the site plugin's call sequence
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
AGENTS.md | 53 ++++++++++++
CONTRIBUTING.md | 26 ++++++
README.md | 97 +++++++++-------------
SECURITY.md | 30 +++++++
.../maven/reporting/MavenMultiPageReport.java | 7 +-
.../org/apache/maven/reporting/MavenReport.java | 31 ++++---
.../maven/reporting/MavenReportException.java | 4 +-
.../maven/reporting/MavenReportRenderer.java | 7 +-
.../org/apache/maven/reporting/package-info.java | 42 ++++++++++
9 files changed, 221 insertions(+), 76 deletions(-)
create mode 100644 AGENTS.md
create mode 100644 CONTRIBUTING.md
create mode 100644 SECURITY.md
create mode 100644 src/main/java/org/apache/maven/reporting/package-info.java
(maven-reporting-api) 01/02: Turn the README into a project page and add contributor, security and agent guides
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-reporting-api.git
commit 1d3a6c32b65483e59eb6ff90e5890bd3a0d76a07
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Oct 23 21:24:52 2026 +0200
Turn the README into a project page and add contributor, security and agent guides
---
AGENTS.md | 53 +++++++++++++++++++++++++++++++
CONTRIBUTING.md | 26 ++++++++++++++++
README.md | 97 ++++++++++++++++++++++++---------------------------------
SECURITY.md | 30 ++++++++++++++++++
4 files changed, 150 insertions(+), 56 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bf6187e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,53 @@
+<!---
+ 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.
+-->
+
+# Agent guide for maven-reporting-api
+
+This file is read by automated agents (security scanners, code
+analyzers, AI assistants) operating on this repository.
+
+## Security
+
+Security model: [SECURITY.md](./SECURITY.md)
+
+Agents that scan this repository should consult `SECURITY.md` and the
+threat model it links before reporting issues.
+
+## Compatibility
+
+This artifact is an API that every Maven report plugin implements, and the
+Maven Site Plugin calls. Binary compatibility matters more than anything else:
+
+- Never add an abstract method to `MavenReport` or `MavenReportRenderer`. A new
+ method must be a `default` method that keeps existing implementations working;
+ `generate(Sink, SinkFactory, Locale)` delegating to `generate(Sink, Locale)` is
+ the pattern.
+- Never make two methods defaults that call each other. A report that overrides
+ neither compiles cleanly and fails with `StackOverflowError` at run time. This
+ is why `getOutputName()` and `generate(Sink, Locale)` stay abstract
+ (#91, #92, fixed by #95 and #96).
+- Check a change against the downstream modules: `AbstractMavenReport` in
+ maven-reporting-impl, `ReportDocumentRenderer` in maven-site-plugin, and
+ maven-reporting-exec.
+
+## Coding
+
+Use test-first programming. Before fixing a bug or implementing a feature,
+write a test that exposes the bug and verify the test fails.
+
+The bytecode floor is Java 8. Before submitting a PR, run `mvn spotless:apply`
+to format the files, then `mvn verify`. Run Spotless with JDK 17 or 21.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9688d01
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,26 @@
+<!---
+ 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.
+-->
+
+# Contributing
+
+Read the [Maven developer guide](https://maven.apache.org/guides/development/guide-maven-development.html)
+before your first pull request. For this repository:
+
+- Report bugs in [GitHub Issues](https://github.com/apache/maven-reporting-api/issues);
+ report security issues privately as [SECURITY.md](SECURITY.md) describes.
+- Discuss new features and API changes on the [dev mailing list](https://maven.apache.org/mailing-lists.html) first.
+- Run `mvn spotless:apply` and `mvn verify` before you push.
diff --git a/README.md b/README.md
index 7c88c23..da710a4 100644
--- a/README.md
+++ b/README.md
@@ -14,71 +14,56 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-Contributing to [Apache Maven Reporting API](https://maven.apache.org.reporting/maven-reporting-api/)
-======================
-[][license]
-[](https://search.maven.org/artifact/org.apache.maven.reporting/maven-reporting-api)
+# Apache Maven Reporting API
+
+[](https://www.apache.org/licenses/LICENSE-2.0)
+[](https://central.sonatype.com/artifact/org.apache.maven.reporting/maven-reporting-api)
[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-api/README.md)
-[][build]
-[][test-results]
+[](https://github.com/apache/maven-reporting-api/actions/workflows/maven-verify.yml)
+
+The contract between the [Maven Site Plugin](https://maven.apache.org/plugins/maven-site-plugin/)
+and every report plugin. A report implements `MavenReport` to declare its name,
+category and output path, and to render itself into a Doxia `Sink`; the site
+plugin calls it and decorates the result with the site skin.
+Report plugins usually extend `AbstractMavenReport` from
+[Maven Reporting Implementation](https://maven.apache.org/shared/maven-reporting-impl/)
+instead of implementing this API directly.
-You have found a bug, or 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, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
+- Documentation: <https://maven.apache.org/shared/maven-reporting-api/>
+- Issues: <https://github.com/apache/maven-reporting-api/issues>
+- Security reports: see [SECURITY.md](SECURITY.md); never a public issue
+- Contributing: see [CONTRIBUTING.md](CONTRIBUTING.md)
-Getting Started
----------------
+## What this is
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss your changes
- on the [dev list][ml-list] first.
- This way you can make sure you're not wasting your time on something that isn't
- considered to be in Apache Maven's scope.
-+ Submit a ticket 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.
-+ Fork the repository on GitHub.
+The artifact holds four types and depends only on `doxia-sink-api`:
-Making and Submitting Changes
---------------
+| Type | Role |
+|---|---|
+| `MavenReport` | The report contract the site plugin calls |
+| `MavenReportRenderer` | Renders one report page |
+| `MavenReportException` | The checked exception a report throws |
+| `MavenMultiPageReport` | Deprecated since 4.1.0; use `MavenReport.generate(Sink, SinkFactory, Locale)` |
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is the
-main channel of communication for contributors.
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually the master branch).
- Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
- patches should only highlight the actual difference, not being disturbed by any formatting issues:
- + Only use spaces for indentation.
- + 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.
- + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
+Where it sits:
-If you plan to contribute on a regular basis, please consider filing a [contributor license agreement][cla].
+```text
+doxia-sink-api
+ └─ maven-reporting-api (this repository)
+ ├─ maven-reporting-impl AbstractMavenReport, which report plugins extend
+ ├─ maven-reporting-exec finds and configures report plugins for the site
+ └─ maven-site-plugin calls MavenReport and renders the pages
+```
-Additional Resources
---------------------
+Every report plugin implements this API, so a new method must be a `default`
+method, never abstract. Releases follow Doxia and come before
+[Maven Reporting Exec](https://maven.apache.org/shared/maven-reporting-exec/),
+Maven Reporting Implementation and the Maven Site Plugin.
-+ [Contributing patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon Account](https://mastodon.social/deck/@ASFMavenProject@fosstodon.org)
+## Build
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]: https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-api/job/master/lastCompletedBuild/testReport/
-[build]: https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-api/job/master/
+```shell
+mvn verify
+```
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..00b1d7c
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,30 @@
+<!---
+ 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.
+-->
+
+# Security policy
+
+## Report a vulnerability
+
+`apache/maven-reporting-api` follows the [Apache Software Foundation security process](https://www.apache.org/security/).
+Report suspected vulnerabilities privately to `security@apache.org`; do not open public
+GitHub issues or pull requests for security reports.
+
+## Threat model
+
+What the project treats as in scope and out of scope, the security
+properties it provides and disclaims, the adversary model, and how
+findings are triaged are documented in <https://github.com/apache/maven/blob/master/THREAT_MODEL.md>.
(maven-reporting-api) 02/02: Fix the Javadoc wording and describe the site plugin's call sequence
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-reporting-api.git
commit 1feb87bccac9421bcb620211d92d1c1149076b2c
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Oct 23 21:36:47 2026 +0200
Fix the Javadoc wording and describe the site plugin's call sequence
---
.../maven/reporting/MavenMultiPageReport.java | 7 ++--
.../org/apache/maven/reporting/MavenReport.java | 31 +++++++++-------
.../maven/reporting/MavenReportException.java | 4 +--
.../maven/reporting/MavenReportRenderer.java | 7 ++--
.../org/apache/maven/reporting/package-info.java | 42 ++++++++++++++++++++++
5 files changed, 71 insertions(+), 20 deletions(-)
diff --git a/src/main/java/org/apache/maven/reporting/MavenMultiPageReport.java b/src/main/java/org/apache/maven/reporting/MavenMultiPageReport.java
index cd421be..2337adf 100644
--- a/src/main/java/org/apache/maven/reporting/MavenMultiPageReport.java
+++ b/src/main/java/org/apache/maven/reporting/MavenMultiPageReport.java
@@ -24,9 +24,10 @@ import org.apache.maven.doxia.sink.Sink;
import org.apache.maven.doxia.sink.SinkFactory;
/**
- * Interface created separately for backwards compatibility. This method
- * would ideally have been added in the {@link MavenReport} interface, and the other 'generate'
- * method dropped. But that would have rendered all reporting mojo's uncompilable and binary incompatible.
+ * A report that renders several pages. Before 4.1.0 this interface was the only way for a report to
+ * receive a {@link SinkFactory}: adding an abstract method to {@link MavenReport} would have broken
+ * every existing report. Since 4.1.0, {@link MavenReport} declares
+ * {@link MavenReport#generate(Sink, SinkFactory, Locale)} as a default method.
*
* @author <a href="mailto:kenney@apache.org">Kenney Westerhof</a>
* @see MavenReport#generate(Sink, Locale)
diff --git a/src/main/java/org/apache/maven/reporting/MavenReport.java b/src/main/java/org/apache/maven/reporting/MavenReport.java
index fe8831e..3fb5307 100644
--- a/src/main/java/org/apache/maven/reporting/MavenReport.java
+++ b/src/main/java/org/apache/maven/reporting/MavenReport.java
@@ -25,7 +25,9 @@ import org.apache.maven.doxia.sink.Sink;
import org.apache.maven.doxia.sink.SinkFactory;
/**
- * The basis for a Maven report.
+ * The basis for a Maven report: a report that the Maven Site Plugin renders into the project site.
+ * Report plugins usually extend {@code AbstractMavenReport} from Maven Reporting Implementation
+ * instead of implementing this interface directly.
*
* @author Brett Porter
* @author <a href="evenisse@apache.org">Emmanuel Venisse</a>
@@ -43,11 +45,10 @@ public interface MavenReport {
String CATEGORY_PROJECT_REPORTS = "Project Reports";
/**
- * Generate the report depending the wanted locale.
- * <br>
- * Mainly used for external reports like javadoc.
+ * Generate the report for the given locale.
* <p>
- * A report that renders several pages also overrides {@link #generate(Sink, SinkFactory, Locale)}.
+ * A report that renders a single page implements only this method. A report that renders several
+ * pages also overrides {@link #generate(Sink, SinkFactory, Locale)}.
*
* @param sink the sink to use for the generation.
* @param locale the wanted locale to generate the report.
@@ -56,7 +57,7 @@ public interface MavenReport {
void generate(Sink sink, Locale locale) throws MavenReportException;
/**
- * Generate the report depending the wanted locale, possibly as several pages.
+ * Generate the report for the given locale, possibly as several pages.
* <p>
* A report that renders a single page ignores {@code sinkFactory}. A report that renders several
* pages uses {@code sinkFactory} to create the sinks for its sub-pages. By default, this method
@@ -75,7 +76,7 @@ public interface MavenReport {
/**
* Get the path relative to {@link #getReportOutputDirectory()} where the report's main output
* file will be written. The last component is the name of the file without any extension. The
- * actual output extension will by added by the sink implementation.
+ * actual output extension is added by the sink implementation.
* <p>
* Note: This method won't be {@code default} anymore when {@link #getOutputName()} is removed.
* You are advised to implement it as soon as possible.
@@ -88,6 +89,9 @@ public interface MavenReport {
}
/**
+ * Get the name of the report's main output file, without any extension.
+ *
+ * @return the output name of this report
* @deprecated Method name does not properly reflect its purpose. Implement and use
* {@link #getOutputPath()} instead.
*/
@@ -134,19 +138,20 @@ public interface MavenReport {
File getReportOutputDirectory();
/**
- * An external report is a report which calls a third party program which generates some reports too.
- * A good example is javadoc tool.
+ * Tell whether this report writes its own output files instead of rendering into the sink, as the
+ * Javadoc report does when it calls the javadoc tool. The Maven Site Plugin does not decorate an
+ * external report with the site skin.
*
- * @return {@code true} if this report is external, {@code false} otherwise.
- * Default should be {@code false}.
+ * @return {@code true} if this report is external, {@code false} otherwise. Most reports return
+ * {@code false}.
*/
boolean isExternalReport();
/**
- * Verify some conditions before generating the report.
+ * Verify some conditions before generating the report, for example that there is something to
+ * report on. The Maven Site Plugin skips a report that returns {@code false}.
*
* @return {@code true} if this report can be generated, {@code false} otherwise.
- * Default should be {@code true}.
* @throws MavenReportException if any
*/
boolean canGenerateReport() throws MavenReportException;
diff --git a/src/main/java/org/apache/maven/reporting/MavenReportException.java b/src/main/java/org/apache/maven/reporting/MavenReportException.java
index b743b78..96cc16c 100644
--- a/src/main/java/org/apache/maven/reporting/MavenReportException.java
+++ b/src/main/java/org/apache/maven/reporting/MavenReportException.java
@@ -30,7 +30,7 @@ public class MavenReportException extends Exception {
public static final long serialVersionUID = -6200353563231163785L;
/**
- * Default constructor.
+ * Create an exception with a message.
*
* @param message the exception message.
*/
@@ -39,7 +39,7 @@ public class MavenReportException extends Exception {
}
/**
- * Other constructor.
+ * Create an exception with a message and a cause.
*
* @param message the exception message.
* @param cause the cause.
diff --git a/src/main/java/org/apache/maven/reporting/MavenReportRenderer.java b/src/main/java/org/apache/maven/reporting/MavenReportRenderer.java
index 242b075..11165a0 100644
--- a/src/main/java/org/apache/maven/reporting/MavenReportRenderer.java
+++ b/src/main/java/org/apache/maven/reporting/MavenReportRenderer.java
@@ -19,7 +19,7 @@
package org.apache.maven.reporting;
/**
- * Basis for rendering report.
+ * Renders the content of a report.
*
* @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
* @author <a href="evenisse@apache.org">Emmanuel Venisse</a>
@@ -27,12 +27,15 @@ package org.apache.maven.reporting;
*/
public interface MavenReportRenderer {
/**
+ * Get the report's title.
+ *
* @return the wanted report's title.
*/
String getTitle();
/**
- * Renderer a report.
+ * Render the report.
+ *
* @throws MavenReportException if any
*/
void render() throws MavenReportException;
diff --git a/src/main/java/org/apache/maven/reporting/package-info.java b/src/main/java/org/apache/maven/reporting/package-info.java
new file mode 100644
index 0000000..94efaca
--- /dev/null
+++ b/src/main/java/org/apache/maven/reporting/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+
+/**
+ * The API between the Maven Site Plugin and the reports it renders.
+ * <p>
+ * A report implements {@link org.apache.maven.reporting.MavenReport}. Report plugins usually extend
+ * {@code AbstractMavenReport} from Maven Reporting Implementation, which also lets the report run as
+ * a standalone goal. For each configured report, the Maven Site Plugin:
+ * <ol>
+ * <li>calls {@link org.apache.maven.reporting.MavenReport#setReportOutputDirectory(java.io.File)
+ * setReportOutputDirectory} with the site output directory;</li>
+ * <li>skips the report if {@link org.apache.maven.reporting.MavenReport#canGenerateReport()
+ * canGenerateReport} returns {@code false};</li>
+ * <li>calls {@link org.apache.maven.reporting.MavenReport#generate(org.apache.maven.doxia.sink.Sink,
+ * org.apache.maven.doxia.sink.SinkFactory, java.util.Locale) generate} with a sink for the main page
+ * and a factory for any sub-pages;</li>
+ * <li>decorates the pages with the site skin, unless
+ * {@link org.apache.maven.reporting.MavenReport#isExternalReport() isExternalReport} returns
+ * {@code true}.</li>
+ * </ol>
+ * <p>
+ * Every report plugin implements this API, so a method added to {@code MavenReport} must be a
+ * {@code default} method, and two default methods must never call each other.
+ */
+package org.apache.maven.reporting;