How does one distinguish version dependent and version-independent documentation? How does one know which files go in which repo?
On Wed, Aug 19, 2026 at 2:59 AM Sylwester Lachiewicz <[email protected]> wrote: > > Hi Everyone, > > Component documentation is currently only published to > https://maven.apache.org/ when a component releases. This makes > documentation fixes for rarely released components, or updates to already > released components, effectively complicated. > > I would like to propose moving the source of version-independent narrative > documentation into maven-site.git, where a commit would republish the > changes immediately. > > To understand the scope, I measured the current estate: there are 1,068 > hand-written site pages across our repositories. While 521 are Velocity > pages, 396 of those use nothing beyond component identity, version, and > escapes. This means 88% of the pages are portable if maven-site can supply > a component's current version to a page. We already half-do this today: > Update.java maintains the version columns of the plugins and shared index > pages, though it currently gets its numbers by scraping the component's own > published page. This would need to be re-based on an authoritative source > first. The site checkers in maven-dist-tool share this same dependency. > > Importantly, published URLs would not break under this approach: > > - Where a component's generated output is a small, stable set of > directories, maven-site can own the path and symlink only those back, > leaving the URL untouched. > - Where this is not possible, a redirect in our existing .htaccess file > can be used. For example, the maven-checkstyle-plugin redirects have > successfully survived many releases. > - Archived, versioned sites would remain unaffected either way. > > I have written up the full details, measurements, and open questions here: > https://github.com/apache/maven-site/issues/1647 > > I am particularly interested in refreshing this discussion now, as I have > recently moved many pages from APT to Markdown, which should make future > contributions and refactoring much easier. > > Regards, > Sylwester -- Elliotte Rusty Harold [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
