`java-version-file` with `asdf`'s `.tool-versions` fails for Corretto, also non-strict semver versions
rtyley opened this issue · comments
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
or8.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:
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 bymajor
version numbersetup-java/src/distributions/corretto/installer.ts
Lines 61 to 62 in 99b8673
Task version:
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
:
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
:
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
Hello @rtyley
Thank you for creating this issue. We will investigate it and get back to you as soon as we have some feedback.
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.
Hello @rtyley, this is a polite reminder to verify if your issue has been resolved with the revised documentation.
Hi @rtyley, could you please confirm whether the revised documentation resolved your issue?
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
, andsetup-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.
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/).
Hello @rtyley, we are closing this issue now. Please feel free to reach out to us for any other issues.