Stick with Java 17 on CI

[Goooler]

Follow up #2918.

[IgnatBeresnev]

Hi! What's the main motivation for using Java 17 everywhere?

It probably doesn't matter in check.yml and gh-pages.yml, but it does matter in the rest of the files for tests and examples. Kotlin can be run under Java 8, so as an official tool we have to support it as well, and so we have to test our changes against Java 8. Migrating all checks to Java 17 will mask some of the problems that I'm currently aware of when it comes to Java compatibility.

At the moment, Java 11 seems to be the default sweet spot between not too old and not too modern, and it's still supported, whereas Java 8 and Java 17 are checked additionally

[Goooler]

We enabled Java 8 as the default in tests via toolchain in #2918, and Java 8 as the compatibility before, now we can bump the running JDK to 17, see #2918 (comment).

[IgnatBeresnev]

Oh, we have the toolchain now, right, completely forgot about it

So basically Java 17 will be used for setting things up and some non-build java executions, and then the toolchain versions will be used for running the actual tests and whatnot?

[Goooler]

Yep. @aSemy WDYT?

[aSemy]

The Java toolchain used to build Dokka projects is set in base-java.gradle.kts

dokka/build-logic/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts

Lines 15 to 19 in 3c3d2e4

	java {
	toolchain {
	languageVersion.set(dokkaBuild.mainJavaVersion)
	}
	}

The actual value is set using the Gradle property org.jetbrains.dokka.javaToolchain.mainCompiler, and the default is 8

dokka/gradle.properties

Line 3 in 3c3d2e4

org.jetbrains.dokka.javaToolchain.mainCompiler=8

When Gradle tries to build Dokka it will realise it needs JDK 8, and try and auto-detect an installed version.

It's similar for the tests: they are configured to run using JDK 8, 11, or 17 via a toolchain, and so Gradle will try and auto-detect those versions too.

Gradle doesn't automatically download JDKs, so they need to be pre-installed, and that's what the setup-java step is for. However, it looks like the latest GitHub runners have JDK 8, 11, and 17 pre-installed, so technically the setup-java step isn't needed for building/testing all (I suspect that the setup-java step was needed in older GitHub runners).

However, Gradle itself is a JVM tool, so it needs Java installed and it the JAVA_HOME environment variable must be set - I guess that's why the setup-java step is needed? I couldn't find any reference to a default JAVA_HOME in the GitHub runners.

In summary:

• Gradle Java Toolchains are used to set the version of Java used to build and test the project
• JDKs 8/11/17 are pre-installed, and will be auto-detected by Gradle to use as Toolchain runners/builders
• setup-java is required to set JAVA_HOME, which Gradle requires to launch itself, but this has no effect on the versions used to be build/test Dokka (they are determined by Java toolchains)

The setup-java action does some caching, but I'm not sure how much impact that has (if any).

If I've understood correctly, perhaps it would be good to add a small bit of docs in CONTRIBUTING.md (feel free to copy/paste/adapt this comment) and add a link next to the setup-java steps?

[Goooler]

May need https://github.com/gradle/foojay-toolchains

[IgnatBeresnev]

@aSemy thank you for the detailed explanation, I'll indeed adapt it and add some other things to CONTRIBUTING.md in a separate PR, will tag you

@Goooler thanks for the contribution!

[Goooler]

@IgnatBeresnev There are JDK 8 and 11 used in TeamCity runners, can we bump them also?

https://scans.gradle.com/s/y4y6wdam2dtua#infrastructure
https://scans.gradle.com/s/yeysww53sshpi#infrastructure