docs: fix README and advanced usage inconsistencies with actual behavior - #1204
Merged
brunoborges merged 1 commit intoAug 5, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
- Fix stale claim that java-version and distribution are always mandatory - Fix security note that claimed no checksum/signature verification exists - Fix jdkfile toolchain example ID (jdkfile_1.6, not Oracle_1.6) - Clarify default toolchain ID derives from the vendor, not the distribution - Drop stale liberica-nik fallback claim; unsupported packages are rejected - Document IBM Semeru and add missing TOC/nav entries - Note that advanced-usage examples target the unreleased v6 on main - Replace retired ubuntu-20.04 runner and fix a heading level Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-focused PR to align README.md and docs/advanced-usage.md with the action’s current behavior (inputs, caching, toolchains, distribution/version resolution), reducing user confusion.
Changes:
- Updated README descriptions and navigation to reflect current behavior (JDK caching, latest resolution behavior, toolchain ID default).
- Updated advanced usage guidance (v6 vs v5 note, distribution/version-file requirements, Semeru example, toolchain ID semantics, security warning wording).
- Expanded/updated TOC and cross-document links to cover additional sections.
| File | Description |
|---|---|
| README.md | Adjusts feature list and input defaults/docs, plus adds advanced-usage navigation links. |
| docs/advanced-usage.md | Updates guidance/examples/TOC to match current behavior and clarify v6 vs v5 usage. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 3
- Review effort level: Lite
Sorry, something went wrong.
Comment thread
README.md
| | `gpg-private-key` | GPG private key to import. | | | ||
| | `gpg-passphrase-env-var` | Environment variable name for the GPG private key passphrase. | `GPG_PASSPHRASE` when a key is set | | ||
| | `mvn-toolchain-id` | Maven Toolchain ID. When multiple Java versions are installed, the number of IDs must match the number of versions. | `${distribution}_${java-version}` | | ||
| | `mvn-toolchain-id` | Maven Toolchain ID. When multiple Java versions are installed, the number of IDs must match the number of versions. | `${vendor}_${java-version}` | |
Comment thread
docs/advanced-usage.md
Comment on lines
+41
to
+48
| > [!NOTE] | ||
| > The examples on this page reference `actions/setup-java@v6`, which is still in | ||
| > development on the `main` branch and is not yet published as a release tag. To | ||
| > try the V6 features documented here (`cache-jdk`, `force-download`, | ||
| > `problem-matcher`, `cache-path`, `cache-read-only`, `java-version: latest`, | ||
| > `oracle-openjdk`, and the `*-env-var` input names), reference | ||
| > `actions/setup-java@main`. For production workflows use the latest stable | ||
| > release, `actions/setup-java@v5`, as shown in the [README](../README.md). |
Comment thread
docs/advanced-usage.md
Comment on lines
50
to
+51
| ## Selecting a Java distribution | ||
| Inputs `java-version` and `distribution` are mandatory and needs to be provided. See [Supported distributions](../README.md#Supported-distributions) for a list of available options. | ||
| `java-version` and `distribution` select what gets installed. `java-version` may be replaced by `java-version-file`, and `distribution` is optional only when `java-version-file` points to a `.sdkmanrc` or `.tool-versions` file that carries a recognized vendor identifier. In every other case both inputs must be provided. See [Supported distributions](../README.md#Supported-distributions) for a list of available options. |
This was referenced Aug 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description:
Several statements in README.md and docs/advanced-usage.md had drifted away from what the action actually does, which is confusing for users trying to figure out what is supported. This audits both documents against action.yml and src/ and corrects the mismatches.
Most of the docs held up: the java-package compatibility table matches JAVA_PACKAGE_CAPABILITIES, the platform/architecture table matches JAVA_PLATFORM_CAPABILITIES (including the armv7 <18 and x86 <12 restrictions), and the checksum-capable distribution list, verify-signature support, SDKMAN/asdf vendor mappings, cache key format, and cache-jdk matrix are all accurate. The changes here are limited to the parts that were not.
Corrected inaccuracies
Coverage and navigation
All same-file and cross-file markdown anchors were validated programmatically after the edits.
Related issue:
N/A
Check list: