slachiewicz opened a new issue, #1647:
URL: https://github.com/apache/maven-site/issues/1647
Component documentation reaches maven.apache.org only when that component
cuts a release. The build writes the site to svn at
`website/components/<type>-archives/<name>-LATEST`, and the release manager
then runs `svnmucc` to swap it into `website/components/<type>/<name>`.
A typo, a dead link, or a stale example therefore cannot be fixed without a
release. `maven-mapping` last released 2015-11-19, `maven-shared-incremental`
2013-04-08 — their documentation is effectively frozen.
I'd like to discuss moving the *source* of version-independent narrative
documentation into this repository, where every commit republishes through the
existing Jenkins job.
## What the estate looks like
There are 1068 hand-written site pages across the `apache/maven-*`
repositories. 521 are Velocity, which makes them look version-coupled, but
classifying what they actually interpolate shows otherwise:
| Velocity reference | occurrences |
|---|---|
| `${project.version}` | 1366 |
| `${project.name}` | 789 |
| `${project.artifactId}` | 666 |
| `${esc.*}` (escapes) | 360 |
| `${project.groupId}` | 94 |
| everything else | thin tail (`${mdoVersion}`, `${thisPlugin}`, …) |
396 of those 521 use nothing beyond component identity, version and escapes.
With the 547 plain pages that is **943 of 1068 (88%) portable**, provided
maven-site can tell a page which component it documents and what version that
component is at.
By page class:
| Class | Total | Velocity |
|---|---|---|
| `faq.*` | 38 | 2 |
| `index.*` | 292 | 69 |
| `usage.*` | 69 | 45 |
| `examples/**` | 302 | 228 |
| `maven-shared-*` (all pages) | 26 | 10 |
## The version source is half-built already, and it breaks on the first move
`Update.java` refreshes the version and date columns of
`content/markdown/plugins/index.md` and `content/markdown/shared/index.md`. It
gets the version by scraping the component's own published page —
`Jsoup.connect(url)` then `doc.select("li#projectVersion")`, the Fluido skin
element.
That is exactly the element that disappears if an index page moves, so
re-basing the lookup on an authoritative source (Central metadata, or
maven-dist-tool's data rather than its rendered HTML) has to come first.
maven-dist-tool's own site checkers (`FluidoHTMLChecker`,
`StylusLeftHTMLChecker`, `StylusRightHTMLChecker`) have the same dependency —
one root cause, two consumers.
The same work can then emit a component-version property source, letting a
central page use `$context.get("version.maven-compiler-plugin")` — the idiom
already used in `guides/development/guide-plugin-documentation.md.vm`. That
also removes the current hand-maintenance of the version columns.
## URLs
Two mechanisms, both with precedent here:
- Where the generated output is a small stable set of directories
(`apidocs`, `xref` — the shared libraries), maven-site can own
`/<type>/<name>/` as a real directory with a nested `components.links`
symlinking only those back. **The URL is unchanged and no redirect is
involved.**
- Where it is `plugin-info.html` plus one unpredictable page per goal (the
plugins), a `Redirect Permanent` in `content/filtered-resources/.htaccess`.
That file is republished on commit and so survives the release-time `svn rm`;
the three `maven-checkstyle-plugin` redirects already there have survived many
releases.
Either way `/<type>-archives/<name>-<version>/` is untouched, so every
released version keeps the documentation it shipped with.
## Suggested sequence
1. **Enablers, no page moves.** Re-base the version lookup off
page-scraping; add the component-version property source; spike the
nested-`components.links` symlink and the svn node-kind transition.
2. **Pilot** one stale shared library end to end — including its
maven-dist-tool entry, since the daily site check will otherwise flag it.
`dist-tool.conf` already supports `> <artifactId> site = <url>` overrides, and
carries one for `maven-wrapper` left from #838.
3. The remaining `maven-shared-*` (26 pages total).
4. Cross-plugin concept pages under `/guides/mini/` — include/exclude
patterns, filtering, skip properties, toolchains, reproducible builds. These
are new pages, so no URL moves.
5. Plugins last, using the redirect mechanism, gated on the property source
landing. `usage.*` is two-thirds Velocity and is exactly where
`${project.version}` belongs, so it cannot go earlier.
## Open questions
1. `/<type>/<name>` currently exists in the content tree as a symlink node.
Replacing it with a real directory of the same name is a node-kind change, and
I don't know whether `scm-publish:publish-scm` computes the delete+add against
its working copy. #838 handled the equivalent with a one-time `svnmucc` prep
before merge — is that acceptable as the general fallback?
2. Does anyone recall this being proposed on dev@ before? I searched MNGSITE
and the issues here and found nothing, but the list archive search is too noisy
to be conclusive.
3. Is the shared libraries the right place to start, or would a plugin pilot
surface problems earlier?
## Notes
- Publishing modernisation (`.asf.yaml` `publish`/`subdir` instead of
svnpubsub) is deliberately **not** part of this. svnpubsub is not deprecated —
INFRA still lists it as supported — and whether git-based publishing preserves
the symlinks this structure depends on is undocumented. Worth its own
discussion, but this should not block behind it.
- Spotless markdown formatting must stay disabled (#1395) — it destroys YAML
front matter.
Related: #838 (the `/wrapper` → `/tools/wrapper` move, the closest
precedent), #671 (the deployment documentation is outdated and would need
updating alongside this).
*This issue was created with AI assistance.*
--
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]
