Repository navigation
docs: fix README and advanced usage inconsistencies with actual behavior - #1204
Merged
brunoborges merged 1 commit intoAug 5, 2026
Merged
Conversation
- 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>
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,
latestresolution 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.
Show a summary per file
| 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
| | `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 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 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.mdanddocs/advanced-usage.mdhad drifted away from what the action actually does, which is confusing for users trying to figure out what is supported. This audits both documents againstaction.ymlandsrc/and corrects the mismatches.Most of the docs held up: the
java-packagecompatibility table matchesJAVA_PACKAGE_CAPABILITIES, the platform/architecture table matchesJAVA_PLATFORM_CAPABILITIES(including thearmv7 <18andx86 <12restrictions), and the checksum-capable distribution list,verify-signaturesupport, SDKMAN/asdf vendor mappings, cache key format, andcache-jdkmatrix are all accurate. The changes here are limited to the parts that were not.Corrected inaccuracies
java-versionanddistributionare mandatory", ignoringjava-version-fileand distribution inference from.sdkmanrc/.tool-versions.verify-signature. Rewritten so the warning (still valid) no longer rests on a false premise, and it now notes that version metadata requests are the unverified link in the chain.jdkfiletoolchain example claimedid: Oracle_1.6.configureToolchainsgenerates${vendor}_${version}, so it isjdkfile_1.6. README'smvn-toolchain-iddefault was also corrected from${distribution}_...to${vendor}_..., and the vendor/ID relationship is now spelled out.liberica-nikrow said unsupportedjava-packagevalues "resolve to the standard bundle".validateJavaPackagerejects them.latestdescription said it always resolves from the distribution's own metadata. Distributions without a release listing (oracle, graalvm) resolve the newest GA major through the Adoptium available-releases API first.Coverage and navigation
@v6onmainwhile the README pins@v5, listing which inputs are V6-only. This was the most likely source of user confusion, since the two documents pin different versions on purpose.ubuntu-20.04runner in an example, and fixed a heading that wash4instead ofh2.All same-file and cross-file markdown anchors were validated programmatically after the edits.
Related issue:
N/A
Check list:
npm run checklocally (format, lint, build, test) and all checks pass. Not run: this is a markdown-only change, nonode_modulesin the worktree, andformat-checkonly covers**/*.{ts,yml,yaml}. No source, test, ordist/files are touched.