SNAPSHOT build docs will references the wrong documentation and can have features and parameters that are not available in the release version. We should only serve documentation for the released version. The problem here is that we can;t update documentation for the released version without a new release.
On Wed, Aug 19, 2026 at 8:23 AM Konrad Windszus <[email protected]> wrote: > > Why not just serving the last SNAPSHOT built of the site by default and just > link the last release version documentation more prominently? > Konrad > > > On 19. Aug 2026, at 08:59, 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 > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > -- Elliotte Rusty Harold [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
