You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "slachiewicz (via GitHub)" <gi...@apache.org> on 2026/08/19 06:42:50 UTC
[I] Centralise version-independent component documentation in maven-site [maven-site]
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: issues-unsubscribe@maven.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz closed issue #1647: Centralise version-independent component documentation in maven-site
URL: https://github.com/apache/maven-site/issues/1647
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5339368233
This sounds like a great idea to me. It's a pity that good contributions (documentation improvements) sometimes have to wait months, if not years, before they come to value (are published). This proposal address that.
As for your open questions:
1. A one-time manual action as a fallback in case automation fails us seems acceptable to me. Too much investigation is probably not going to be worth it.
2. I can't recall such a proposal.
3. Why not both? A pilot with one shared library and one plugin? No matter which one surfaces most problems, we'll find them :-)
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5343829378
another dream approach that I had to this question about "not waiting for release to get content published" was to bring easier navigation from release to release
this would avoid too much change, and just easy navigation from "latest release" (= the current content) to "current SNAPSHOT" (= see if anything has been updated) and to "archived past releases" (when some have been kept)
happy to test different approaches
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5344927411
or we coudl be more open to use not only Maven based tools to create our main 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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5412457516
#1657 is a test for a partial solution to the "bring easier navigation from release to release" approach
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5343763484
IIUC, this would be a little bit like merging doxia-site into maven-site #1646 , but for plugins and components = projects that are versioned/released?
if we do that (let's dream this is feasible from a content perspective), left menu and breadcrumb will require some rework to get a site with a reasonable navigation: for example, the breadcrumb topic we face for doxia-site into maven-site https://github.com/apache/maven-site/issues/1645#issuecomment-5340818720 will become an absolute necessity
and I'm eager to see the left menu merging automation
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5351438598
I think this is releated to https://github.com/apache/maven-gh-actions-shared/issues/212 where I also brought up the need to update page without the need of a release to fix errors, improve docs/examples etc.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5340430404
trying to improve is a great idea
but I can't understand the proposal: can we have a concrete description on one component or plugin, please?
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Centralise version-independent component documentation in maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1647:
URL: https://github.com/apache/maven-site/issues/1647#issuecomment-5380637785
doing something that works won't be about genAI writing a long text, or saying something like "we coudl be more open to use not only Maven based tools to create our main site .."
when I see how #1645 has been closed before even trying to finish something that is easy but still requires consistency and work, I now know this issue won't do anything useful
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org