java-version-file with asdf's .tool-versions fails for Corretto, also non-strict semver versions

[rtyley]

Description:
Support for asdf's .tool-versions file was added to the java-version-file parameter with PR #606 in response to issue #579 - unfortunately, there's a difference between what asdf requires for this file, vs what setup-java supports:

asdf requires that the Java version in .tool-versions is fully specified

So a file will typically look like this:

java corretto-21.0.2.13.1

If you shorten the version, eg to 21.0.2 or 21, and run asdf install java, you'll get this error from asdf:

Unknown release: corretto-21.0.2

setup-java only supports major versions or strict 3-part semver

setup-java supports version numbers of 1 to 3 dot-separated integers (eg major to major.minor.patch). This excludes several valid version numbers - here are some examples:

• all Corretto version numbers, which are always at least 4-part (eg 21.0.2.13.1 or 8.322.06.4)
• Zulu 8.74.0.17
• sapmachine 11.0.16.1
• Oracle 18.0.2.1
• Microsoft 17.0.1.12.1

setup-java only supports major versions for Corretto

This is probably due to AWS Corretto only providing a simple API for looking up Java versions, that only supports getting the latest version for each major version of Java:

setup-java/src/distributions/corretto/installer.ts

Line 100 in 99b8673

'https://corretto.github.io/corretto-downloads/latest_links/indexmap_with_checksum.json';

So, Corretto with the java-version-file parameter is doubly unsupported:

• Corretto 5-part version numbers don't match the regex's used by setup-java to verify version numbers
• Even if Corretto version numbers were accepted, corretto/installer.ts wouldn't be able to locate and download the specific Corretto version, because it can only support finding by major version number

  setup-java/src/distributions/corretto/installer.ts

  Lines 61 to 62 in 99b8673

  	if (version.includes('.')) {
  	throw new Error('Only major versions are supported');

Task version:

v4.2.1

Platform:

• Ubuntu
• macOS
• Windows

Runner type:

• Hosted
• Self-hosted

Repro steps:
Define an invocation of actions/setup-java in a workflow, and point java-version-file to .tool-versions:

.github/workflows/ci.yml :

        uses: actions/setup-java@v4
        with:
          distribution: zulu
          java-version-file: .tool-versions

In .tool-versions, define a version like zulu-8.58.0.13 - and verify that works by executing asdf install java:

.tool-versions :

java zulu-8.58.0.13

The let the ci.yml workflow run.

Expected behavior:
Ideally, if the .tool-versions file is valid for asdf, setup-java should install that precise version of Java. This means setup-java needs to accept all versions output by asdf list-all java.

Where a distribution has been specified that setup-java is unable to search for precise Java versions (ie Corretto), if the user has set a java-version-accept-any-matching-major-version parameter to true it should just install the latest version of Java for that major version.

Actual behavior:

zulu-8.58.0.13 in .tool-versions (guardian/etag-caching@959d4dc) :
https://github.com/guardian/etag-caching/actions/runs/8470107933/job/23207054598#step:3:16

No supported version was found in file .tool-versions

cc @aparnajyothi-y @mahabaleshwars @HarithaVattikuti

[HarithaVattikuti]

Hello @rtyley
Thank you for creating this issue. We will investigate it and get back to you as soon as we have some feedback.

[mahabaleshwars]

Hello @rtyley, I hope this message finds you well. I wanted to kindly bring to your attention some observations regarding the adaptation of our support strategy for the asdf's tool versions file. Specifically, we've noted certain discrepancies with Java versions that do not entirely align with Semver standards.

Moreover, it has come to our attention that some of the currently supported distributions are not listed in the asdf java available versions. To ensure consistency and adherence to best practices, our focus will now be directed towards maintaining .tool-versions files that fully comply with Semver standards.

For your convenience, please note that we have also updated the documentation. Thank you for your attention to this matter.

[mahabaleshwars]

Hello @rtyley, this is a polite reminder to verify if your issue has been resolved with the revised documentation.

[mahabaleshwars]

Hi @rtyley, could you please confirm whether the revised documentation resolved your issue?

[rtyley]

Hi @mahabaleshwars!

To ensure consistency and adherence to best practices, our focus will now be directed towards maintaining .tool-versions files that fully comply with Semver standards.

I can see the appeal of choosing a standard, but I think there's a possibility that strict semver (MAJOR.MINOR.PATCH) is not an applicable standard, when major JDK distributors like AWS, Oracle, Microsoft, Azul & SAP are releasing JDK versions that do not confirm to semver.

If the organisations releasing JDKs are not using semver, then what's so good about setup-java requiring semver?

could you please confirm whether the revised documentation resolved your issue?

Personally, I wouldn't say that the changes made to the documentation so far resolve the issue.

For your convenience, please note that we have also updated the documentation.

Incidentally, I appreciate you linked to the documentation, but as it's a large document, and you were asking me to comment on a change, it would actually be more helpful to include a link to the PR that made the change, which I've found is #622.

So, I think there are two reasonable ways to address the issue, and updating the documentation is one of them - obviously, I'd much prefer that setup-java supported the ideal behaviour I suggested in this issue description (if a .tool-versions file is valid for asdf, setup-java should install that precise version of Java, or a least make a best effort to install the right major version, etc), and I appreciate that's substantial work. If you don't have the available capacity for those alterations, it's good to instead update the documentation to warn users that support for .tool-versions is seriously limited (ie, it will reject a large proportion of valid asdf .tool-versions files).

Unfortunately, I feel the changes in #622 aren't quite clear enough to help users to understand the limitations - essentially the explanation added in the PR was just adding ", adhering to Semantic Versioning (semver)" to the end of "...the .tool-versions file supports version specifications in accordance with asdf":

Problems with this:

• This doesn't link to the semver standard at https://semver.org/, so users are relying on their own recall of what the semver standard is (eg, they may well think it's just numbers-separated-by-dots, and not recall it requires specifically 3 numbers)
• setup-java does not support the full semver standard, because the semver standard is actually quite extensive and allows pre-release suffixes like -alpha-a.b-c-somethinglong+build.1-aef.1-its-okay or just -snapshot.1, and setup-java doesn't support that
• It would probably be clearer to explicitly state the actual supported format, eg "for versions that strictly adhere to MAJOR.MINOR.PATCH version numbers".

...personally, I don't think adhering to the semver standard here is a necessarily a gain for setup-java, and the truth is setup-java only has partial support for it.

Note that even if AWS Corretto did use strict semver, setup-java still wouldn't be able to support .tool-versions files that specify Corretto versions, because AWS only provide an API for looking up Corretto artifacts by major version number - semver numbering is not really the blocker there, so requiring it doesn't seem to help? To me, it would be better to support a accept-any-matching-major-version parameter instead, to allow falling back to supported distribution lookup methods.

[mahabaleshwars]

Hello @rtyley, your efforts to pinpoint the problem are appreciated. The 'setup-java' currently adheres to semver, which includes the Major.Minor.Patch-'pre-release version'+metadata format. We included a reference link to the semver documentation for additional clarity. However, our support for .tool-versions is presently limited to versions compliant with semver (https://semver.org/).

[mahabaleshwars]

Hello @rtyley, we have updated the documentation to reference the semver link through this PR. Could you please confirm if the feedback provided adequately addresses the concern raised?

[mahabaleshwars]

Hello @rtyley, we are closing this issue now. Please feel free to reach out to us for any other issues.