slachiewicz opened a new pull request, #12711:
URL: https://github.com/apache/maven/pull/12711
Ports the site documentation from APT to Markdown on `maven-4.0.x`,
mirroring apache/maven#12682 on `master`.
All **38** pages converted; no `.apt`/`.apt.vm` files remain. Two commits,
same shape as master's: a rename-only commit so `git log --follow` survives,
then the conversion. **Please merge or rebase rather than squash**, so the
rename stays visible.
### This is a port of master's work, not a fresh conversion
All 38 APT sources are byte-identical between `maven-4.0.x` and master's
pre-conversion commit `0bf573bd6a`, so all 38 take master's already-reviewed
Markdown as their base. Zero needed converting from 4.0.x's own APT. The rename
set matches master's `6a1b3e39c2`.
Of the three test files, two are taken from master verbatim.
`ArtifactHandlerTest.java` was hand-merged: master's copy carries an unrelated
`length() == 0` → `isEmpty()` modernisation that 4.0.x does not have, so only
the doc-related change was taken. This PR introduces no unrelated diff.
### Front matter is restored
Master's conversion commit dropped the YAML front matter, so pages lost
`<meta name="author">` and `<meta name="date">`, and titles degraded from
`Introduction – Maven Artifact` to `Maven Artifact – Maven Artifact`. Master
fixed that afterwards in `096d59ec94`. This branch carries the front matter
from the outset, reconstructed from the original APT headers — 38 files,
byte-identical in size to master's fix.
One deliberate difference from master: master writes `author: ` with a
trailing space on all 38 lines, which `git diff --check` flags. This writes
`author:`. Nothing enforces it today, so master's is latent lint noise rather
than a failure, but it seemed wrong to copy.
### Verification
`mvn site` before and after with `target/site` wiped between runs — an
incremental run silently compares against stale output. **All 590 generated
pages** compared, not only the 38 converted, through a normaliser covering
`<title>`, `author`/`date` metadata, visible text, link targets, and heading /
table-cell / list-item / `<pre>` structure.
**588 identical, 2 differing** — `configuration-management` and
`getting-to-container-configured-mojos`, whose only differences are the
intended `${…}` and `<developerConnection/>` repairs plus three structural
edits master made deliberately. The 557 untouched pages coming out identical is
what shows there was no collateral damage.
The three tests that read these tables — `ArtifactHandlerTest` and both
`DefaultTypeProviderTest`s — pass, and were **mutation-tested** rather than
merely observed green: a table cell was altered in each and each failed as
expected. `apache-rat:check` passes with front matter ahead of the licence
header.
The 5 `its/` pages cannot be built directly (`mvn site -f its/pom.xml` fails
with `skin cannot be null`, pre-existing, which is why master left them
unverified). They were rendered in scratch projects with an explicit skin
instead, and come out identical including metadata — so all 38 are verified,
not 33.
### Limits of that evidence
- The normaliser strips tags, so an anchor-id-only, CSS-class or image-`src`
change would not show. Anchors were covered by a separate grep; images and
styling were not checked.
- The `its/` harness used synthetic `<name>`/`<description>`, so Velocity
references were confirmed to resolve and the structure to match, not the exact
substituted strings.
- Both builds ran with `-Dmaven.javadoc.skip=true -DskipTests`; apidocs are
not part of the 590.
- Only the three table-reading tests were run, not the full suite.
- This covers Doxia's HTML output only — nothing about the deployed site.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
