Each 9.4.x maintenance release breaks links to preceding version's documentation

[wilkinsona]

A Spring Boot user has reported a problem with Spring Boot's reference documentation linking to Jetty's documentation. Spring Boot's reference documentation links to the Jetty documentation for the specific version of Jetty that it built against. For example, the documentation for Spring Boot 2.2.4 links to https://www.eclipse.org/jetty/documentation/9.4.25.v20191220. Unfortunately, this link is now broken. As far as I can tell, the breakage occurred when 9.4.26 was released as its documentation replaced the documentation for 9.4.25.

I'm aware of the 9.4.x link but this points to snapshot documentation which we'd prefer not to use. I'm also aware of the current link, but this will, presumably, eventually link to 9.5.x or 10.x so it will become inaccurate over time.

Would it be possible to avoid breaking links by publishing new documentation in addition to rather than in place of the existing documentation. Failing that, would it be possible to provide a link for 9.4 that points to the latest release rather than the latest snapshot?

[joakime]

We have a "current" at https://www.eclipse.org/jetty/javadoc/current/
But that's not enough detail. Especially as we are working towards Jetty 10.x (Jakarta EE 8 based) and 11.x (Jakarta EE 9 based) atm.

[WalkerWatch]

@wilkinsona Let me discuss with @jmcc0nn3ll. I think the idea has merits, as I know other projects in addition to Spring link to our documentation. We would need to create something like /documentation/9.4.x/ for each major release version, in addition to /documentation/current, which should be feasible.

[stale]

This issue has been automatically marked as stale because it has been a full year without activity. It will be closed if no further activity occurs. Thank you for your contributions.

[wilkinsona]

We’ve stopped linking to Jetty’s documentation as a workaround for this problem. We’d still welcome a fix for it as it would allow us to reinstate the links.

[joakime]

@jmcc0nn3ll @WalkerWatch looks like the script to move docs to https://archive.eclipse.org/jetty/ isn't working again.

[jmcc0nn3ll]

It is not working because we stopped archiving things. I am open to replacing all of this but question the value of exposing generally the same documentation with updated version identifiers. Major versions of Jetty may have unique documentation but within that major version each release of documentation is more an improvement then chronicling new changes or features. IMO third parties should point to the best version of each major release documentation, which is the latest release. I can be convinced otherwise of course, but knowing the way our documentation has been developed for years now that is how I see things.