docs: state an explicit minimum Node.js version in the README - #443
Open
AmaadMartin wants to merge 1 commit into
Open
docs: state an explicit minimum Node.js version in the README#443AmaadMartin wants to merge 1 commit into
AmaadMartin wants to merge 1 commit into
Conversation
The Installation prerequisite read "a current Node.js LTS release", which is not mechanically checkable and silently asserts a higher floor every time a new LTS line opens. Replace it with the concrete floor the repository can actually justify. 20.19 is the smallest version that satisfies every engines.node constraint in the committed package-lock.json: 20.18.9 violates 6 of them (vite's ^20.19.0 || >=22.12.0 and five copies of eslint-visitor-keys' ^20.19.0 || ^22.13.0 || >=24), while 20.19.0 violates none. Nothing in the resolved tree requires a major above 20.
This was referenced Aug 1, 2026
Open
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.
Please ensure you have read the contribution guide before creating a pull request.
Link to Issue or Description of Change
Closes: #issue_number
Related: #issue_number
No open issue tracks this. Context: the wording being replaced was introduced by review feedback on google#526.
Problem:
README.md:55— the only Node.js requirement statement anywhere inthe repository — reads:
> **Prerequisite:** ADK for TypeScript requires a current Node.js LTS release.Three concrete defects:
LTS release" against
node -v, and a reviewer cannot compare it againstanything in the repo.
October and again at each end-of-life, so the identical sentence asserts a
strictly rising floor over time. A user who complied in one cycle is silently
non-compliant later, with no diff to point at.
measured floor across the resolved dependency graph is Node 20, so the line
both fails to warn a Node 18 user that they are genuinely below the floor and
wrongly discourages a Node 20 user who is fine.
google#526 originally landed "Node.js 18 or newer"; the reviewer
correctly objected that 18 was end-of-life and that a hardcoded number goes
stale, and the fix removed the number entirely. That traded a wrong number for
no number. This PR restores an explicit floor, but derives it from the
repository's own dependency constraints rather than from a guess — which answers
the original objection instead of dodging it.
Solution: one line of Markdown.
git diff --statisREADME.md | 2 +-— 1 file, 1 insertion, 1 deletion.Where 20.19 comes from (measured, not asserted). There is no
enginesfieldin any manifest, no
.nvmrc/.node-version/.tool-versions, and bothworkflows call
actions/setup-node@v6with nowith:block — so CI pinsnothing and there is no tested-version set that could honestly be cited. The one
source of truth in the repo is the 797
engines.nodeconstraints in thecommitted
package-lock.json. Evaluating every one of them withsemver:eslint-visitor-keyswants^22.13.0)20.19.0 is therefore the exact minimum on the 20 line — the smallest version
that contradicts nothing in the lockfile. The six constraints that 20.18.9
violates are
vite@7.3.5(^20.19.0 || >=22.12.0) and five nested copies ofeslint-visitor-keys(^20.19.0 || ^22.13.0 || >=24). The tightest runtimeconstraints are
@google/genai@2.9.0(>=20.0.0, direct dep ofcore) andcommander@14.0.3(>=20, direct dep ofdev). Nothing anywhere in the treerequires a major above 20, and both the root and
devmanifests pin@types/node@^20.12.7, so the codebase is type-checked against the Node 20 APIsurface. A claim of 22 or 24 would be unsupported by the repository.
Note this is a dependency floor, not a statement about Node's own support
calendar — deliberately, since any such statement would reintroduce the
calendar-drift defect being fixed here. The new text contains no time-relative
wording and makes no claim about which versions CI tests, because CI pins none.
Deliberately out of scope (called out so the omission is not read as an
oversight): declaring the floor in machine-readable form —
engines.nodein thefour manifests plus a pinned
node-version/.nvmrcin the two workflows. Thatis what would make this claim enforceable by npm and provable by CI, and it is a
user-visible change (npm emits
EBADENGINE) that deserves its own review. It isalready queued as a separate task.
Collision check. Before writing anything I listed all 344 open PRs on the
fork (
gh pr list --state open --limit 1000) and, separately, diffed the rootREADME.mdblob of every remote branch againstmain: no branch changes thePrerequisite:line, so there is no competing implementation. Four PRs aretopically adjacent but file-disjoint — #133 (
.nvmrc+engines.node+ CIpins), #416, #428 and #406 (CI Node pinning) — none of them touches
README.md. This PR is branched frommainrather than stacked, because thediffs do not overlap and stacking would drag eight unrelated files in.
PR title. Titled
docs:on purpose.release-please-config.jsonlinksmain,adk,devtoolsandintegrationsunder onelinked-versionsgroup,and merges here are squashed on the PR title — so a
feat:/fix:title wouldcut a release of all four packages for a one-line docs edit.
docs:bumpsnothing.
Testing Plan
Please describe the tests that you ran to verify your changes. This is required for all PRs that are not small documentation or typo fixes.
This is a small documentation fix: zero executable lines are added, so there is
nothing to unit test and the new-line-coverage requirement is vacuously
satisfied (0 new lines, 0 uncovered).
No test was added, on purpose. A test that reads
README.mdand matches/Node\.js 20\.19/would be a change-detector anti-test: it pins marketing copy,breaks on any future rewording, and verifies nothing about ADK's behaviour. The
durable enforcement mechanism for a Node floor is
engines.nodeplus a pinned CInode-version, which is the separately queued follow-up described above — not aVitest assertion.
In place of the usual "prove the test can fail" mutation, the number itself was
falsified against the lockfile: the bisect in the table above shows 20.18.9
leaves 6 unsatisfied constraints and 20.19.0 leaves 0, so the claim would have
been detectably wrong at any lower value. Reproduce with:
Unit Tests:
[ ] I have added or updated unit tests for my change. — not applicable, see above.
[x] All unit tests pass locally. — the repo suite was not run in full (a
Markdown-only diff cannot perturb it, and full-suite runs are avoided);
a targeted run confirms the tree is healthy:
npx vitest run --project unit:core core/test/utils/case_utils_test.ts→ 1 file, 6 tests passed.
Local validation on the exact pushed commit (
e949811e) — every gate thevalidationworkflow runs, all exit 0:npm installpackage-lock.jsonunchanged afterwards)npm run buildnpm run format:check**/*.ts; does not readREADME.md)npx prettier --check README.mdnpm run lintnpm run docs:checktypedoc.jsonsets"readme": "none", so this is a no-regression smoke check here)npx secretlint "**/*"npx vitest run --project unit:core core/test/utils/case_utils_test.tsPostconditions verified:
grep -n LTS README.md→ no hits;grep -n 20.19 README.md→ exactly one hit on line 55; line length 71 (under the 80-columnconvention
.prettierrc.jssets for this file); LF endings, no trailingwhitespace, single trailing newline;
git status --shortshows exactly onemodified path.
Manual End-to-End (E2E) Tests:
Please provide instructions on how to manually test your changes, including any necessary setup or configuration.
Installation section shows one blockquote reading Prerequisite: ADK for
TypeScript requires Node.js 20.19 or newer., correctly styled, immediately
above the
npm install @google/adkfence, with one blank line either side.node -vand confirm the sentence is now decidable in a singlecomparison — the exact property the previous wording lacked.
confirm nothing in the resolved tree excludes Node 20.19.
Checklist
[x] I have read the CONTRIBUTING.md document.
[x] I have performed a self-review of my own code.
[x] I have commented my code, particularly in hard-to-understand areas. — n/a, Markdown prose only.
[x] I have added tests that prove my fix is effective or that my feature works. — no test added, deliberately; see the Testing Plan for the reasoning and for the lockfile bisect used instead.
[x] New and existing unit tests pass locally with my changes.
CI
All checks pass on
e949811e:run-tests (ubuntu-latest),run-tests (macos-latest),run-tests (windows-latest), the cross-languagerun-testsjob,
check-licenseandauto-assign.Disclosing one detail rather than hiding it: on the first attempt
run-tests (windows-latest)failed withcore/test/code_executors/unsafe_local_code_executor_test.ts > should execute shell code and return stdout — Test timed out in 5000ms(1 failed / 2679passed). That is a pre-existing Windows flake, not a regression, and the
evidence is:
reach a shell-execution test.
b390217e,main, zero changes) also failsrun-tests (windows-latest)— run30669370416— there on a differenttest,
tests/integration/adk_web/webui_test.ts. Different test each run isthe signature of a Windows timing flake, and Windows is already red on
main.npx vitest run --project unit:core core/test/code_executors/unsafe_local_code_executor_test.tspasses locally: 18/18.
no code change in between.
The underlying Windows-flake work is already tracked separately; it is out of
scope here.