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-exec.git


The following commit(s) were added to refs/heads/master by this push:
     new 69863e1  Refresh the site index and README for 2.1.0
69863e1 is described below

commit 69863e1cb84a6b36eead8e73e3bd197a7d150c83
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 23:09:03 2026 +0000

    Refresh the site index and README for 2.1.0
---
 README.md                     |  83 ++++++-------------
 src/site/markdown/index.md.vm | 184 +++++++++++++++++++++++++++++++++---------
 src/site/site.xml             |   3 +-
 3 files changed, 170 insertions(+), 100 deletions(-)

diff --git a/README.md b/README.md
index 769a596..6df6f0d 100644
--- a/README.md
+++ b/README.md
@@ -14,71 +14,38 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-Contributing to [Apache Maven Reporting 
Executor](https://maven.apache.org.reporting/maven-reporting-exec/)
-======================
-
-[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license]
-[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.reporting/maven-reporting-exec.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.reporting/maven-reporting-exec)
-[![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/reporting/maven-reporting-exec/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-exec/README.md)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-exec/job/master.svg)][build]
-[![Jenkins 
tests](https://img.shields.io/jenkins/t/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-exec/job/master.svg)][test-results]
 
+# Apache Maven Reporting Executor
 
-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.
+[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.reporting/maven-reporting-exec.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.apache.maven.reporting/maven-reporting-exec)
+[![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/reporting/maven-reporting-exec/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-exec/README.md)
+[![Verify](https://github.com/apache/maven-reporting-exec/actions/workflows/maven-verify.yml/badge.svg)](https://github.com/apache/maven-reporting-exec/actions/workflows/maven-verify.yml)
 
-Getting Started
----------------
+Turns the report plugins in a POM's `<reporting>` section into configured 
`MavenReport` instances. The
+[Maven Site Plugin](https://maven.apache.org/plugins/maven-site-plugin/) calls 
it during `mvn site`: it resolves each
+report plugin's version, merges its configuration with 
`build/pluginManagement`, loads it in its own class realm and
+runs any forked lifecycle a report needs. Plugins that render reports 
themselves can call `MavenReportExecutor` the
+same way.
 
-+ 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.
+Requires Java 8 or later; built against the Maven 3.9 core API.
 
-Making and Submitting Changes
---------------
+- Documentation: <https://maven.apache.org/shared/maven-reporting-exec/>
+- Issues: <https://github.com/apache/maven-reporting-exec/issues>
 
-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.
+## Build
 
-If you plan to contribute on a regular basis, please consider filing a 
[contributor license agreement][cla].
+```shell
+mvn verify
+```
 
-Additional Resources
---------------------
+This also runs the integration tests under `src/it`, which drive report 
plugins through the executor, including
+forked lifecycles and report plugins built on different Doxia versions. Run 
one of them with
+`mvn verify -Dinvoker.test=forked-lifecycle`.
 
-+ [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/@[email protected])
+## Contributing
 
-[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-exec/job/master/lastCompletedBuild/testReport/
-[build]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-exec/job/master/
+Send pull requests against `master`; discuss larger changes on the
+[developer mailing list](https://maven.apache.org/mailing-lists.html) first. 
Spotless enforces the
+[Maven code style](https://maven.apache.org/developers/conventions/code.html) 
during the build; run
+`mvn spotless:apply` before you push. Pull request titles become entries in 
the release notes.
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 50fbc0f..c69e92d 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -19,55 +19,159 @@ under the License.
 
 # ${project.name}
 
-Classes to prepare report plugins execution with Maven 3, through 
[MavenReportExecutor](./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html)
 
([implementation](./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html)).
+Maven Reporting Executor turns the report plugins listed in a POM's 
`<reporting>` section into configured
+[`MavenReport`](https://maven.apache.org/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html)
+instances, ready to render. Maven core does not prepare reports itself, so the
+[Maven Site Plugin](https://maven.apache.org/plugins/maven-site-plugin/) calls 
this library during `mvn site`, and
+any plugin that renders reports on its own can do the same.
 
-Contrary to Maven 2.x:
+For each report plugin, the executor:
 
-1. report `<version>` explicit definition is optional:  
-    if no version is specified for a report plugin, version is determined by
-    1. searching for the plugin in the `build/plugins` section of the pom,
-    1. searching for the plugin in the `build/pluginManagement` section of the 
pom,
-    1. asking 
[PluginVersionResolver](/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html)
 to get a fallback version and display a warning as it's not a recommended use,
-1. plugin configuration from `build/pluginManagement` is injected into 
`reporting/plugins` (since Maven Reporting Executor 1.2, which is [used by 
Maven Site Plugin 3.4](/plugins/maven-site-plugin/history.html)).
+1. resolves the plugin version,
+2. selects the report goals to run,
+3. merges the report configuration with the plugin's `build/pluginManagement` 
configuration,
+4. loads the plugin in its own class realm and configures each report goal as 
a mojo,
+5. runs the forked lifecycle a report asks for, such as `generate-sources` for 
`jxr:jxr`.
 
-Notice on now obsolete reportPlugin format
-------------------------------------------
+This page covers what a site user sees, how to call the executor from your own 
plugin, and what changes in 2.1.0.
 
-Since 1.4 (used by Maven Site Plugin 3.7), the request can (and should) be 
populated from [pom's `<reporting.plugins>` 
section](/ref/current/maven-model/maven.html#class_reporting), injected in Mojo 
parameter as `${esc.d}{project.reporting.plugins}` default value:
+${esc.h}${esc.h} Requirements
 
-```java
-    @Parameter( defaultValue = "${esc.d}{project.reporting.plugins}", readonly 
= true )
-    private org.apache.maven.model.ReportPlugin[] reportingPlugins;
+Version ${project.version} needs Java ${javaVersion} or later. It is built 
against the Maven ${mavenVersion} core API
+and no longer needs `maven-compat`. Version 2.0.1 is the last release built 
against Maven 3.6.3.
+
+${esc.h}${esc.h} How report plugins are configured during `mvn site`
+
+${esc.h}${esc.h}${esc.h} Plugin version
+
+When a report plugin in `<reporting>` has no `<version>`, the executor takes 
the first version it finds in:
+
+1. the `build/plugins` section of the POM,
+2. the `build/pluginManagement` section of the POM,
+3. the plugin repositories, through Maven's `PluginVersionResolver`. This last 
step logs a warning, because the
+   build is no longer reproducible:
+
+```text
+[WARNING] Report plugin org.apache.maven.plugins:maven-jxr-plugin has an empty 
version.
+[WARNING]
+[WARNING] It is highly recommended to fix these problems because they threaten 
the stability of your build.
+[WARNING]
+[WARNING] For this reason, future Maven versions might no longer support 
building such malformed projects.
+[INFO] Configuring report plugin maven-jxr-plugin:3.6.0
 ```
 
-This section is kept to explain what happened in previous releases of the 
component, but this approach has been abandoned so far after discovering major 
limitations: see [Maven Site Plugin 3.9.0 
documentation](/plugins-archives/maven-site-plugin-3.9.0/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance)
 for more details.
-
-Report plugins can be configured in `<configuration>` element of 
`maven-site-plugin` or any other report building plugin with following XML 
model corresponding to plugin's 
`List<`[`ReportPlugin`](./apidocs/org/apache/maven/reporting/exec/ReportPlugin.html)`>`
 parameter:
-
-```xml
-<reportPlugins>
-  <reportPlugin>
-    <groupId/>
-    <artifactId/>
-    <version/>
-    <configuration/>
-    <reports/>
-    <reportSets>
-      <reportSet>
-        <id/>
-        <configuration/>
-        <reports/>
-      </reportSet>
-    </reportSets>
-  </reportPlugin>
-</reportPlugins>
+Declare the version in `<reporting>` or in `build/pluginManagement` to avoid 
it.
+
+${esc.h}${esc.h}${esc.h} Report goals
+
+If the plugin lists `<reports>` in a `<reportSet>`, only those goals run, and 
the log says `Configured`. Without a
+report list, every goal of the plugin that implements `MavenReport` runs, and 
the log says `Detected`:
+
+```text
+[INFO] Configuring report plugin maven-project-info-reports-plugin:3.9.0
+[INFO] Configured 2 reports for maven-project-info-reports-plugin:3.9.0: 
index, summary
+[INFO] Configuring report plugin maven-jxr-plugin:3.6.0
+[INFO] Detected 4 reports for maven-jxr-plugin:3.6.0: jxr, jxr-no-fork, 
test-jxr, test-jxr-no-fork
 ```
 
-Notice this is the model from plugins in [`<reporting>` section of 
POM](/ref/current/maven-model/maven.html#class_reporting):
+Detected goals that aggregate reports run only in the execution root of a 
multi-module build with `pom` packaging.
+A goal listed explicitly always runs, and a listed goal that is not a report 
logs a warning and is skipped.
+
+${esc.h}${esc.h}${esc.h} Report configuration
+
+The executor merges configuration in this order, with the first source winning:
+
+1. the `<reportSet>` `<configuration>`,
+2. the report plugin's `<configuration>` in `<reporting>`,
+3. the plugin's `<configuration>` in `build/pluginManagement`,
+4. the mojo's default values.
+
+Parameters that the report goal does not declare are dropped. The 
`<dependencies>` of the same plugin in
+`build/plugins`, or else in `build/pluginManagement`, are added to the report 
plugin's class path.
 
-- without `<inherited>` element: reporting plugins configuration inheritance 
is not supported at this level (see 
[MSITE-484](https://issues.apache.org/jira/browse/MSITE-484)),
-- with additional `<reports>` list outside `<reportSet>` that simplifies 
reports configuration in usual cases.
+${esc.h}${esc.h} Run report plugins from your own plugin
+
+Inject 
[`MavenReportExecutor`](./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html),
 fill a
+[`MavenReportExecutorRequest`](./apidocs/org/apache/maven/reporting/exec/MavenReportExecutorRequest.html),
 and
+render each returned 
[`MavenReportExecution`](./apidocs/org/apache/maven/reporting/exec/MavenReportExecution.html)
+with the context class loader set to the execution's class loader. This is 
what the Maven Site Plugin does:
+
+```java
+@Parameter(defaultValue = "${esc.d}{session}", readonly = true, required = 
true)
+private MavenSession session;
+
+@Parameter(defaultValue = "${esc.d}{project}", readonly = true, required = 
true)
+private MavenProject project;
+
+@Parameter(defaultValue = "${esc.d}{project.reporting.plugins}", readonly = 
true)
+private org.apache.maven.model.ReportPlugin[] reportingPlugins;
+
+@Parameter(defaultValue = "${esc.d}{mojoExecution}", readonly = true, required 
= true)
+private MojoExecution mojoExecution;
+
+private final MavenReportExecutor mavenReportExecutor; // injected through the 
mojo's @Inject constructor
+
+List<MavenReportExecution> prepareReports() throws MojoExecutionException {
+    MavenReportExecutorRequest request = new MavenReportExecutorRequest();
+    request.setMavenSession(session);
+    request.setExecutionId(mojoExecution.getExecutionId());
+    request.setProject(project);
+    request.setReportPlugins(reportingPlugins);
+    return mavenReportExecutor.buildMavenReports(request);
+}
+
+void render(MavenReportExecution execution, Sink sink, SinkFactory 
sinkFactory, Locale locale)
+        throws MavenReportException {
+    if (!execution.canGenerateReport()) {
+        return;
+    }
+    ClassLoader original = Thread.currentThread().getContextClassLoader();
+    try {
+        
Thread.currentThread().setContextClassLoader(execution.getClassLoader());
+        execution.getMavenReport().generate(sink, sinkFactory, locale);
+    } finally {
+        Thread.currentThread().setContextClassLoader(original);
+    }
+}
+```
+
+[`canGenerateReport()`](./apidocs/org/apache/maven/reporting/exec/MavenReportExecution.html)
 already switches the
+class loader for you. `generate(Sink, SinkFactory, Locale)` is the Maven 
Reporting API 4.1.0 entry point; it also
+reaches reports that implement only `generate(Sink, Locale)`.
+
+${esc.h}${esc.h}${esc.h} Classes shared with the calling plugin
+
+Each report plugin gets its own class realm, whose parent is the calling 
plugin's class loader. These packages always
+come from the calling plugin, so that the report and the caller agree on the 
`MavenReport` and `Sink` types:
+
+- `org.apache.maven.reporting`
+- `org.apache.maven.doxia.siterenderer`
+- `org.apache.maven.doxia.sink`
+- `org.apache.maven.doxia.util`
+
+The artifacts `maven-reporting-api`, `doxia-sink-api` and 
`doxia-site-renderer` are dropped from the report plugin's
+own dependencies for the same reason. During `mvn site`, a report therefore 
runs with the Maven Site Plugin's
+Reporting API and Doxia versions, not the ones in its own POM; see
+[`DefaultMavenReportExecutor`](https://github.com/apache/maven-reporting-exec/blob/${project.scm.tag}/src/main/java/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.java)
 for the
+exact lists.
+
+${esc.h}${esc.h} Upgrading to 2.1.0
+
+- `MavenReportExecutorRequest.getLocalRepository()` and 
`setLocalRepository(ArtifactRepository)`, deprecated since
+  2.0.0-M10, are removed. Nothing read the value; delete the call.
+- The library no longer depends on `maven-compat` and is built against Maven 
${mavenVersion} instead of 3.6.3.
+- It depends on Maven Reporting API 4.1.0 and Doxia Sink API 2.2.0.
+
+Notice on now obsolete reportPlugin format
+------------------------------------------
 
-Maven 3 core makes an automatic transformation of `<reporting>` POM section 
(which supports configuration inheritance) to `maven-site-plugin`'s 
`reportPlugins` configuration through the 
[ReportingConverter](/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html)
 component.
+Before 1.4, the request was filled from a `<reportPlugins>` parameter in the 
configuration of
+`maven-site-plugin` or another plugin that renders reports. That format has 
been abandoned: it did not support configuration inheritance
+([MSITE-484](https://issues.apache.org/jira/browse/MSITE-484)), and Maven core 
converted `<reporting>` into it only
+for the Maven Site Plugin, not for other plugins that render reports. See the
+[Maven Site Plugin 3.8.2 
documentation](https://maven.apache.org/plugins-archives/maven-site-plugin-3.8.2/maven-3.html#New_Configuration_.28Maven_3_only.2C_no_reports_configuration_inheritance.29)
+for the history.
 
-But Maven 3 does not do the same job for any other plugin wanting to use 
reports, like `maven-pdf-plugin` for example: this is one of the key 
limitations that made Maven team drop this approach.
+Since 1.4, fill the request from the POM's `<reporting>` section instead, with
+`setReportPlugins(org.apache.maven.model.ReportPlugin[])` and the 
`${esc.d}{project.reporting.plugins}` expression
+shown above.
diff --git a/src/site/site.xml b/src/site/site.xml
index 349567c..5d73c9d 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -24,8 +24,7 @@ under the License.
     <menu name="Overview">
       <item name="Introduction" href="index.html"/>
       <item name="Javadoc" href="apidocs/index.html"/>
-      <item name="Source Xref" href="xref/index.html"/>
-      <item name="License" href="http://www.apache.org/licenses/"/>
+      <item name="License" href="https://www.apache.org/licenses/"/>
       <item name="Download" href="download.html"/>
     </menu>
 

Reply via email to