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


The following commit(s) were added to refs/heads/master by this push:
     new 5df6939b Explain how report sets are selected
5df6939b is described below

commit 5df6939b09718487a20405ecb18a38b99cdf256c
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 4 09:05:43 2026 +0000

    Explain how report sets are selected
    
    Fills the report sets placeholder in the site guide with the selection rule 
from maven-site-plugin#820 (MSITE-726), and links it from the plugin 
configuration and multi-module guides.
---
 .../guides/mini/guide-configuring-plugins.md       |  2 ++
 .../markdown/guides/mini/guide-multimodule-site.md |  2 ++
 content/markdown/guides/mini/guide-site.md         | 40 +++++++++++++++++++++-
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/content/markdown/guides/mini/guide-configuring-plugins.md 
b/content/markdown/guides/mini/guide-configuring-plugins.md
index 55eaaf41..4451e387 100644
--- a/content/markdown/guides/mini/guide-configuring-plugins.md
+++ b/content/markdown/guides/mini/guide-configuring-plugins.md
@@ -646,6 +646,8 @@ You can configure a reporting plugin using the 
`<reportSets>` tag. This is most
    ```
 2. Refer to each Plugin Documentation (i.e. plugin-info.html) to know the 
available report goals.
 
+For which report sets run in which module of a multi-module build, see [How 
Report Sets Are Selected](./guide-site.html#How_Report_Sets_Are_Selected).
+
 ### Using the `<inherited>` Tag In Reporting Plugins
 
 Similar to the build plugins, to break the inheritance, you can use the 
`<inherited>` tag:
diff --git a/content/markdown/guides/mini/guide-multimodule-site.md 
b/content/markdown/guides/mini/guide-multimodule-site.md
index 86024658..f67edb37 100644
--- a/content/markdown/guides/mini/guide-multimodule-site.md
+++ b/content/markdown/guides/mini/guide-multimodule-site.md
@@ -91,3 +91,5 @@ To benefit from aggregate reports, configure a report set in 
the parent POM, and
   ...
 </project>
 ```
+
+The aggregate report then runs only in the parent. For which reports run in 
the modules, see [How Report Sets Are 
Selected](./guide-site.html#How_Report_Sets_Are_Selected).
diff --git a/content/markdown/guides/mini/guide-site.md 
b/content/markdown/guides/mini/guide-site.md
index 95a14b97..a4c644c1 100644
--- a/content/markdown/guides/mini/guide-site.md
+++ b/content/markdown/guides/mini/guide-site.md
@@ -368,7 +368,45 @@ Many other plugins provide reporting goals: look for "R" 
(Reporting) value in th
 
 **Note:** Many report plugins provide a parameter called `outputDirectory` or 
similar to specify the destination for their report outputs. This parameter is 
only relevant if the report plugin is run standalone, i.e. by invocation 
directly from the command line. In contrast, when reports are generated as part 
of the site, the configuration of the Maven Site Plugin will determine the 
effective output directory to ensure that all reports end up in a central 
location.
 
-<!--TODO: explain report sets-->
+### How Report Sets Are Selected
+
+The Maven Site Plugin does not choose one report set. For every module it runs 
the reports in these steps:
+
+1. Maven's model inheritance merges the `<reporting>` section of the parent 
POMs into the module. A `<reportSet>` with `<inherited>false</inherited>` is 
not passed on to child modules; any other report set is.
+2. The reports named in _all_ the report sets of a plugin are collected, 
whatever their `<id>`. A plugin without report sets gets every report goal it 
has, except the aggregator goals, which are added only in the root of the 
reactor when it has `pom` packaging and declares modules.
+3. Each collected report is asked whether it can run for the module (for 
example, a source cross-reference or Javadoc report has nothing to do in a 
`pom` module). Reports that cannot run are skipped, and the log says `Skipping 
<plugin>:<goal> report` for the ones you listed explicitly.
+
+So on a `pom` module the only report that is left is usually the aggregate 
one, even if you listed several report sets: the other reports were collected 
but skipped. To see what was collected and what was skipped, look at the lines 
`Configured n reports for ...` and `Skipping ...` in the output of `mvn site`.
+
+For example, with the `maven-jxr-plugin` configured in a parent POM as follows:
+
+```xml
+<reportSets>
+  <reportSet>
+    <id>default</id>
+    <reports><report>jxr</report></reports>
+  </reportSet>
+  <reportSet>
+    <id>aggregate</id>
+    <inherited>false</inherited>
+    <reports><report>aggregate</report></reports>
+  </reportSet>
+  <reportSet>
+    <id>tests</id>
+    <reports><report>test-jxr</report></reports>
+  </reportSet>
+</reportSets>
+```
+
+the site build of a reactor reports:
+
+| Module | Configured reports | Generated |
+|--------|--------------------|-----------|
+| Parent POM (`pom` packaging, has modules) | `jxr`, `aggregate`, `test-jxr` | 
`aggregate` (`jxr` and `test-jxr` are skipped) |
+| Child with `jar` packaging, main and test sources | `jxr`, `test-jxr` | 
`jxr`, `test-jxr` |
+| Child with `pom` packaging | `jxr`, `test-jxr` | none (both are skipped) |
+
+For the elements of a report set, see [Report Sets in the POM 
reference](../../pom.html#Report_Sets).
 
 ## Internationalization
 

Reply via email to