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/)
-======================
-
-[![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-impl.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.reporting/maven-reporting-impl)
-[![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-impl/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-impl/README.md)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-reporting-impl/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-impl/job/master.svg)][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.
+[![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-impl.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.apache.maven.reporting/maven-reporting-impl)
+[![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-impl/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/reporting/maven-reporting-impl/README.md)
+[![Verify](https://github.com/apache/maven-reporting-impl/actions/workflows/maven-verify.yml/badge.svg)](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>
 

Reply via email to