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-impl.git
The following commit(s) were added to refs/heads/master by this push:
new 3e5c4b1 Refresh the site index and README for 4.1.0
3e5c4b1 is described below
commit 3e5c4b197cfb2b4383b0a24e41765169988ac0da
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 22:40:12 2026 +0000
Refresh the site index and README for 4.1.0
Replaces the 2.3 upgrade notes with what 4.1.0 changes for subclasses
(#251).
---
README.md | 83 +++++++++++++------------------------------
src/site/markdown/index.md.vm | 60 +++++++++++++++++++++----------
src/site/site.xml | 2 +-
3 files changed, 67 insertions(+), 78 deletions(-)
diff --git a/README.md b/README.md
index cf0af5b..9ff140e 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
Implementation](https://maven.apache.org.reporting/maven-reporting-impl/)
-======================
-
-[][license]
-[](https://search.maven.org/artifact/org.apache.maven.reporting/maven-reporting-impl)
-[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-impl/README.md)
-[][build]
-[][test-results]
+# Apache Maven Reporting Implementation
-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.
+[](https://www.apache.org/licenses/LICENSE-2.0)
+[](https://central.sonatype.com/artifact/org.apache.maven.reporting/maven-reporting-impl)
+[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-impl/README.md)
+[](https://github.com/apache/maven-reporting-impl/actions/workflows/maven-verify.yml)
-Getting Started
----------------
+The base class for Maven report plugins. A report extends
`AbstractMavenReport`, implements
+`executeReport(Locale)`, and then runs both inside `mvn site`, through the
+[Maven Reporting API](https://maven.apache.org/shared/maven-reporting-api/),
and as a standalone goal that renders
+its own page with the site skin, or writes it in a Doxia markup format with
`-Doutput.format`.
-+ 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.
+- Documentation: <https://maven.apache.org/shared/maven-reporting-impl/>
+- Writing a report plugin:
<https://maven.apache.org/guides/plugin/guide-java-report-plugin-development.html>
+- Issues: <https://github.com/apache/maven-reporting-impl/issues>
-Making and Submitting Changes
---------------
+## Build
-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.
+```shell
+mvn verify
+```
-If you plan to contribute on a regular basis, please consider filing a
[contributor license agreement][cla].
+The integration tests under `src/it` build a sample report plugin and run it
both ways:
-Additional Resources
---------------------
+```shell
+mvn -P run-its verify
+```
-+ [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-impl/job/master/lastCompletedBuild/testReport/
-[build]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-impl/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 e970aa8..0434246 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -26,38 +26,60 @@ under the License.
# ${project.name}
-Abstract classes to manage report generation, which can be run both:
+Maven Reporting Implementation provides
+[`AbstractMavenReport`](./apidocs/org/apache/maven/reporting/AbstractMavenReport.html),
the base class for report
+plugins. A report that extends it runs in two ways:
-1\. as part of a **site generation**, as a
[maven-reporting-api](../maven-reporting-api/)'s
[`MavenReport`](../maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html),
+1. as part of **site generation**, when the [Maven Site
Plugin](/plugins/maven-site-plugin/) calls it through the
+ [Maven Reporting API](../maven-reporting-api/)'s
+
[`MavenReport`](../maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html)
interface.
+2. as a **standalone goal**, for example `mvn myreport:report`, through the
Maven Plugin API's
+
[`Mojo`](/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/Mojo.html)
interface. The report then
+ renders its own HTML page with the site skin from the project's
`src/site/site.xml`, or, with
+ `-Doutput.format=<format>` such as `xdoc` or `apt`, writes the report in
that Doxia format without a skin.
-2\. or as a direct standalone **goal invocation**, as a
[maven-plugin-api](/ref/current/maven-plugin-api/)'s
[`Mojo`](/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/Mojo.html).
+Either way, `AbstractMavenReport` calls your `executeReport(Locale)` method,
which writes the report through
+`getSink()`. Reports with several pages create a sink for each extra page with
`getSinkFactory()`.
-The two APIs implementations are provided by
[`AbstractMavenReport`](./apidocs/org/apache/maven/reporting/AbstractMavenReport.html),
that delegates to extender's `executeReport( Locale )` reporting method
implementation.
+The [guide to developing a report
plugin](/guides/plugin/guide-java-report-plugin-development.html) walks through
a
+complete example. The integration tests in this repository hold a working
report plugin:
+[`src/it/setup-reporting-plugin`](https://github.com/apache/maven-reporting-impl/tree/${project.scm.tag}/src/it/setup-reporting-plugin).
-Notice that Doxia version used at runtime varies between **site generation**
and **goal invocation**:
+${esc.h}${esc.h} Which Doxia version runs
-1\. when used as report during **site generation**, `maven-site-plugin`
provides Doxia implementation to the plugin, overriding normal plugin
dependency: see
[DefaultMavenReportExecutor](/shared/maven-reporting-exec/xref/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html)
in [`maven-reporting-exec`](/shared/maven-reporting-exec/).
+The Doxia version used at runtime differs between the two modes:
-2\. when used as a direct standalone **goal invocation**, Doxia implementation
used is the version used during plugin compilation and kept as transitive
dependency of the plugin.
+1. During **site generation**, the Maven Site Plugin provides Doxia and the
Reporting API to the report, overriding
+ the plugin's own dependencies; see
+
[`DefaultMavenReportExecutor`](/shared/maven-reporting-exec/apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html)
+ in [Maven Reporting Exec](/shared/maven-reporting-exec/).
+2. As a **standalone goal**, the report uses the Doxia version it depends on,
which comes in transitively through
+ this library.
-Usage
------
+Code a report against the oldest Maven Site Plugin you support; the
+[Reporting API compatibility
notes](../maven-reporting-api/index.html${esc.hash}Compatibility_notes_for_report_authors)
+list the current pitfalls.
-A full working sample is included in `maven-reporting-impl` ITs, which are
part of [the component source tree](../scm.html): see
[`src/it/setup-reporting-plugin`](https://github.com/apache/maven-reporting-impl/tree/${project.scm.tag}/src/it/setup-reporting-plugin).
+${esc.h}${esc.h} Upgrading to 4.1.0
-History
--------
+Version 4.1.0 builds on Reporting API 4.1.0, Doxia 2.2.0 and Doxia Sitetools
2.1.0. Recompile your report against
+it; two changes can affect subclasses:
-|release date|maven-maven-reporting-impl|[Doxia](/doxia/)|
+- The protected field `siteRenderer` and the method `getSiteRenderer()` now
use the type `SiteRenderer` instead of the
+ deprecated `Renderer`. An override that returns the field must declare
`SiteRenderer` as its return type.
+- A new parameter, `mavenSession`, holds the Maven session. The site
descriptor of a standalone report is now
+ interpolated with user and system properties too, as the Maven Site Plugin
already does.
+
+Multi-page reports keep working with Maven Site Plugin 3.22.0 and older:
`AbstractMavenReport` still implements the
+deprecated `MavenMultiPageReport` interface, which those versions require.
+
+${esc.h}${esc.h} History
+
+|Release date|maven-reporting-impl|[Doxia](/doxia/)|
|:---:|:---:|:---:|
|2024-10|4.0.0|**2.0.0**|
|2022-08|[3.2.0](/shared-archives/maven-reporting-impl-3.2.0/)|1.11.1|
|2022-02|[3.1.0](/shared-archives/maven-reporting-impl-3.1.0/)|1.11.1|
|2017-06|[3.0.0](/shared-archives/maven-reporting-impl-3.0.0/)|1.7|
-See also Maven Site Plugin's
[history](/plugins/maven-site-plugin/history.html#maven-site-plugin-vs-doxia-vs-doxia-sitetools).
-
-#[[### Upgrading to `maven-reporting-impl 2.3+`]]#
-
-When upgrading a reporting plugin from an old version of
`maven-reporting-impl` to version 2.3 or more, a lot of copy/pasted code can be
removed by upgrading the plugin to [plugin-tools with Java 5
annotations](/plugin-tools/maven-plugin-tools-annotations/): see
[MSHARED-347](https://issues.apache.org/jira/browse/MSHARED-347) for more
details.
-
+See also the Maven Site Plugin's
[history](/plugins/maven-site-plugin/history.html#maven-site-plugin-vs-doxia-vs-doxia-sitetools).
diff --git a/src/site/site.xml b/src/site/site.xml
index c81050f..6e2d34a 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -27,7 +27,7 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
- <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>