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
The following commit(s) were added to refs/heads/master by this push:
new bbebb5f Add a site index for report authors
bbebb5f is described below
commit bbebb5fe54fd791c3e7c7c08be3c6aff4c29db94
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 22:40:12 2026 +0000
Add a site index for report authors
The 4.1.0 compatibility notes were only in the GitHub release notes; the
site home page now carries them.
---
src/site/markdown/index.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++
src/site/site.xml | 2 +-
2 files changed, 67 insertions(+), 1 deletion(-)
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..1e0b9a6
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,66 @@
+<!--
+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.
+-->
+
+# Apache Maven Reporting API
+
+The Reporting API is the contract between the [Maven Site
Plugin](/plugins/maven-site-plugin/) and every report
+plugin. A report implements
[`MavenReport`](./apidocs/org/apache/maven/reporting/MavenReport.html) to
declare its
+name, category and output path, and to render itself into a Doxia
[`Sink`](/doxia/doxia/doxia-sink-api/); the site
+plugin calls it and decorates the result with the site skin.
+
+To write a report plugin, extend `AbstractMavenReport` from
+[Maven Reporting Implementation](../maven-reporting-impl/) instead of
implementing this API directly: it implements
+both `MavenReport` and `Mojo`, so the report also runs as a standalone goal.
The
+[guide to developing a report
plugin](/guides/plugin/guide-java-report-plugin-development.html) walks through
a
+complete example.
+
+## Types
+
+The API holds four types and depends only on `doxia-sink-api`.
+
+| Type | Role |
+|---|---|
+| [`MavenReport`](./apidocs/org/apache/maven/reporting/MavenReport.html) | The
report contract the site plugin calls. |
+|
[`MavenReportRenderer`](./apidocs/org/apache/maven/reporting/MavenReportRenderer.html)
| Renders one report page. |
+|
[`MavenReportException`](./apidocs/org/apache/maven/reporting/MavenReportException.html)
| The checked exception a report throws. |
+|
[`MavenMultiPageReport`](./apidocs/org/apache/maven/reporting/MavenMultiPageReport.html)
| Deprecated since 4.1.0: use `MavenReport.generate(Sink, SinkFactory,
Locale)`. |
+
+A report that writes more than one page receives a `SinkFactory` in
`generate(Sink, SinkFactory, Locale)` and creates
+one sink per extra page. The default implementation ignores the factory and
calls `generate(Sink, Locale)`.
+
+## Compatibility notes for report authors
+
+During site generation, report plugins run with the Reporting API and Doxia
classes that the Maven Site Plugin
+supplies, not with the versions they were compiled against. Two consequences
for 4.1.0:
+
+- Keep implementing `MavenMultiPageReport` for now. Maven Site Plugin 3.22.0
and older load Reporting API 4.0.0 and
+ call the multi-page `generate` only through that interface. To keep the
deprecation warning in one place,
+ implement it through a package-private interface annotated with
`@SuppressWarnings("deprecation")`, as
+ `AbstractMavenReport` in Maven Reporting Implementation does.
+- Keep using `org.apache.maven.doxia.sink.impl.SinkEventAttributeSet`,
although Doxia 2.2.0 deprecates it. Its
+ replacement in `doxia-sink-api` 2.2.0 is missing under Maven Site Plugin
3.22.0 and older, and the report is
+ skipped with a `LinkageError`.
+
+## History
+
+| Release date | Reporting API | [Doxia](/doxia/) |
+|:---:|:---:|:---:|
+| 2026-10 | 4.1.0 | 2.2.0 |
+| 2024-10 | [4.0.0](/shared-archives/maven-reporting-api-4.0.0/) | **2.0.0** |
+| 2022-07 | [3.1.1](/shared-archives/maven-reporting-api-3.1.1/) | 1.11.1 |
diff --git a/src/site/site.xml b/src/site/site.xml
index 63fb84f..5461271 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -28,7 +28,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>