docs: drop benchmark numbers from the JDK caching section - #1205
Merged
brunoborges merged 2 commits intoAug 5, 2026
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the project documentation around setup-java behavior and usage examples, including JDK caching visibility and several advanced-usage clarifications.
Changes:
- Document JDK caching more prominently in the README (feature bullet + advanced-usage nav links) and expand the README’s
java-version: latestexplanation. - Update
docs/advanced-usage.mdwith a V6-on-main note, add an IBM Semeru example, and refine several sections (package compatibility wording, toolchains ID/vendor explanation, TLS security warning, headings/examples).
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds JDK caching to the “What it does” list, expands latest documentation, adjusts toolchain ID default text, and extends advanced-usage link list. |
| docs/advanced-usage.md | Adds TOC entries + a v6-on-main note, includes IBM Semeru docs, and refines several advanced usage sections (package compatibility, examples, toolchains, TLS warning). |
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: 2
- Review effort level: Lite
The JDK caching section quoted informal figures from the feature PR. The setup-java-benchmarks repository now has a JDK cache scenario workflow that reproduces the comparison end to end, so cite its numbers across two independent runs and name the workflow instead. Also record the cold-run cost, the flat build-step control, and the fact that the job-level median is noisier than the setup-step median, so the tradeoff is explicit rather than implying the speedup is free or precise. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 664777db-7250-417d-b94d-d5529ec3fec2
brunoborges
force-pushed
the
brunoborges-docs-accuracy-audit
branch
2 times, most recently
from
August 5, 2026 03:23
9047341 to
3bb23dd
Compare
brunoborges
changed the title
The JDK caching section quoted specific benchmark timings and linked an external benchmark repository. Point-in-time measurements from one runner, distribution, and project go stale silently and invite readers to treat them as a guarantee, and the reference documentation is not the right home for them. Describe the tradeoff qualitatively instead: a warm run restores the JDK rather than downloading it, the first run pays the upload, and every cached identity consumes cache storage. That is the part that stays true regardless of runner, distribution, JDK size, and network. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 664777db-7250-417d-b94d-d5529ec3fec2
brunoborges
force-pushed
the
brunoborges-docs-accuracy-audit
branch
from
August 5, 2026 03:24
3bb23dd to
6b5f505
Compare
3 tasks
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:
The JDK caching section in
docs/advanced-usage.mdquoted specific benchmark timings (median warmsetup-javafalling from 7s to 3s, median warm job from 24s to 18s, 175.3 MiB of storage) and linked an external benchmark repository. This removes both.Point-in-time measurements do not belong in reference documentation. They come from one runner type, one distribution, one JDK size, and one project, and they go stale silently as runner images, vendor CDNs, and the action itself change. A reader has no way to tell how far their situation is from the measured one, so a concrete number invites being read as a guarantee rather than as one data point. The external repository link has the same problem in reverse: it points readers away from the reference docs to something they then have to interpret.
What replaces it is the part that stays true regardless of environment: a warm run restores the installed JDK instead of downloading, verifying, and extracting it; the first run pays to upload it; and every cached identity consumes repository cache storage. The existing guidance about which factors drive the result (runner, distribution, JDK size, network, cache eviction pressure) is kept.
The billed-minutes aside was also dropped. It described how GitHub bills job time rather than anything about
setup-java, so it belonged in the Actions billing documentation rather than here.Net effect is 4 insertions and 8 deletions in one file. No behavior change.
Related issue:
N/A. Follow-up to #1201 and #1204.
Check list:
npm run checklocally (format, lint, build, test) and all checks pass. Not run: this change touches onlydocs/advanced-usage.md, andformat-checkcovers**/*.{ts,yml,yaml}only, so markdown is outside every check in that script.