[Idea] Hosted javadocs for LTS versions of Jenkins

Contributing
1

Hey everyone,

I was browsing the hosted javadocs and noticed that, https://javadoc.jenkins.io/ hosts javadocs for the latest weekly version only.

It would probably make sense to host javadocs for LTS versions in too (there are currently none in in the javadoc archives) but most preferably, for the newest LTS version.

That would definitely be in favor of people using LTS versions of Jenkins to find the correct methds to use, when using the hosted javadocs.

Looking over jenkins-infra/javadoc highlights that javadocs are still built using java 8 too :eyes:

2

I thought it was quite rare that an LTS version was allowed to introduce an API level change when compared to its matching weekly baseline. I haven’t run the detailed check, but I would expect no relevant difference between the Javadoc of 2.346 and the Javadoc of 2.346.1 or 2.346.2.

I don’t object to also publishing LTS Javadoc in the Javadoc archives, but I’m not sure that it will generate any different behavior.

Can you explain further what you hope to gain by showing the Javadoc of the LTS releases?

Thanks for noting that! It is another location that needs to have its use of Java 8 replaced with Java 11. I’ve created JENKINS-69033 to track that change.

I would use the words “packages” rather than “builds” to describe what those scripts do. Those scripts download the Javadoc that has been generated by the build processes of plugins, components, and core and then packages those different Javadoc components into the javadoc.jenkins.io site.

Java 11 is already used to build the Javadoc from the Java source files of Jenkins releases that require Java 11 as their minimum version. You can see the Java 11 Javadoc browsing experience in the “Latest Core Javadoc” page linked from the Developer Javadoc page. That page is quite different from the “Jenkins 2.346 Javadoc” that was built with Java 8.

3

but I would expect no relevant difference between the Javadoc of 2.346 and the Javadoc of 2.346.1 or 2.346.2

I meant in comparison to weekly releases. Given that only the latest core javadoc is hoisted, someone using 2.346.x as baseline finds unusable API for their version when selecting the core javadocs, because it contains changes that aren’t available on your baseline.

4

I kinda think java docs should be using lts (stable) not weekly (unstable) so developers use APIs that are already released.

I think having two copies would lead to conclusions
Confusing google results.

Then again as someone who rarely does core/plugin dev I rarely use it at all

5

That’s why the Javadoc page in the developer documentation provides links to:

Plugin maintainers choose their minimum Jenkins version and if they choose an LTS baseline as recommended, then they can refer to the Javadoc for that LTS version.

6

Stable is already available in the Jenkins Javadoc archives. If the top level page shows stable, then we need another place to show the most recent release. I would much prefer to retain the current structure rather than move the latest to another location so that we can replace latest with LTS baseline on https://javadoc.jenkins.io

7

I’ve confirmed that https://javadoc.jenkins.io is running with the latest changes, including the switch from Java 8 to Java 11.

8

I am not a developer/contributor to either Jenkins core or plugins. While I have played around on plugin development, my primary use case for referencing the Javadoc relates to groovy scripting. Nevertheless, I am confused …

I see two primary audiences (three if you include the lookie-loo references) for Javadoc:

  • those who are contributing to Jenkins core, who would obviously want to have reference to the latest Javadoc. Though, I expect the “latest” would come generated from their local instance.
  • those who are developing and contributing to plugins, who per the development guidelines to plugins, should be:

… using newest LTS version that doesn’t exclude a majority of your existing users

Currently recommended versions

At the moment, the Jenkins releases 2.319.3 and 2.332.4 make good core dependencies. You could also consider 2.346.1 if there are specific reasons, like new features, to want something newer; 2.289.3 and 2.303.3 would be reasonable conservative choices.

Given there is only one reference at https://javadoc.jenkins.io/, the question is what audience is best served by the “default version” and what should be served up to them? That is a decision best left to the experts.

Perhaps, an alternative exists… I can’t recall the last time I landed at the JavaDoc Docs- jenkins.io/doc/developer/javadoc page, but us there any way the JavaDoc Overview page can either offer up a version selector to the archive versions [ Latest Weekly | Latest LTS | Oldest reasonable LTS ] or provide a helpful link back to the JavaDoc Docs page, making it easier for users to find the other versions? That would seem to provide a great deal of utility.