Skip to content

Keep verbatim source blocks working with Doxia 1 - #245

Merged
slachiewicz merged 1 commit into
apache:masterfrom
slachiewicz:doxia1-compatible-verbatim-source
Aug 8, 2026
Merged

Keep verbatim source blocks working with Doxia 1#245
slachiewicz merged 1 commit into
apache:masterfrom
slachiewicz:doxia1-compatible-verbatim-source

Conversation

@slachiewicz

@slachiewicz slachiewicz commented Aug 8, 2026

Copy link
Copy Markdown
Member

Finishes what #243 started. That PR fixed verbatimText and verbatimLink, and called out verbatimSource as the remaining half; this is it.

SinkEventAttributeSet.SOURCE arrived in Doxia 2, where DOXIA-685 introduced it in place of BOXED. Reading it therefore ends in a NoSuchFieldError whenever the Maven Site Plugin in use still provides Doxia 1, since a report plugin renders with the Doxia the Site Plugin provides rather than its own. Maven 3.9.x still binds maven-site-plugin 3.12.1 by default, so that is the common case rather than an exotic one.

Unlike the verbatim() case, this one is not reachable from maven-project-info-reports-plugin, which is why apache/maven-project-info-reports-plugin#103 only ever showed the other symptom. It is reachable though: PluginOverviewRenderer in maven-plugin-report-plugin calls verbatimSource.

The change

Build the attribute set rather than reading the constant:

sink.verbatim(new SinkEventAttributeSet(SinkEventAttributes.DECORATION, "source"));

SinkEventAttributes.DECORATION and the varargs constructor both exist in Doxia 1 and Doxia 2, and DECORATION is a compile time String constant, so nothing here is resolved against a class that might be missing.

Output is unchanged on Doxia 2: the constant holds exactly this attribute, and the existing integration test still asserts <pre class="prettyprint"><code>…</code></pre>. On Doxia 1 the decoration value source is simply not one it recognises, so the block renders as a plain verbatim block. Losing the styling there is a lot better than losing the report.

Note this leaves #184 open, since building the set still needs SinkEventAttributeSet from the impl package. That is a packaging problem, waiting on apache/maven-doxia#1073; this is a Doxia 1 versus 2 problem, and the two are independent.

Test

The new test asserts both the attribute value and, with assertNotSame, that the set is not the constant itself. The identity check is the part that matters: content alone would pass either way, since the constant carries the same attribute. Reverting the production change fails it:

SinkEventAttributeSet.SOURCE does not exist in Doxia 1 and must not be read ==> expected: not same but was: < decoration=source>

mvn verify green: unit tests, all 6 ITs, and rat.

SinkEventAttributeSet.SOURCE was added in Doxia 2, replacing BOXED, so
reading it ends in NoSuchFieldError whenever the Maven Site Plugin in use
still provides Doxia 1. That is the same failure that MPIR issue 103
reported for verbatimText and verbatimLink, one method over, and it is
reachable: maven-plugin-report-plugin calls verbatimSource.

Build the attribute set instead. The decoration key and the varargs
constructor both exist in Doxia 1 and 2, so the block renders as source
on Doxia 2 as before, and degrades to a plain verbatim block on Doxia 1
rather than failing the report.
@slachiewicz
slachiewicz merged commit db31d8d into apache:master Aug 8, 2026
17 checks passed
@github-actions github-actions Bot added this to the 4.0.1 milestone Aug 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant