[ZEPPELIN-6501] Reference source-of-truth for toolchain versions in AGENTS.md#5284
Merged
tbonelee merged 1 commit intoJul 8, 2026
Merged
Conversation
…GENTS.md Replace hardcoded toolchain version literals in AGENTS.md with references to their source of truth, so the doc cannot drift again: - Java / Scala -> root pom.xml (java.version, scala.binary.version) - Project version-> root pom.xml <version> - Frontend -> zeppelin-web-angular/package.json (engines.node, @angular/core) - Maven -> .mvn/wrapper/maven-wrapper.properties (the ./mvnw wrapper pin) The listed frontend versions had already gone stale (Angular 13 / Node 18 vs the actual Angular 21 / Node >=22.12). AGENTS.md is read by AI coding agents, for which a single source of truth matters more than seeing the exact number inline on one page -- a stale literal actively misleads. Editorial guidance that is not a version literal is kept (e.g. "use exactly that JDK major, not a newer/older one"). CLAUDE.md is a symlink to AGENTS.md and is covered automatically.
pan3793
approved these changes
Jul 8, 2026
Member
|
I also find a lot of stale info in our docs, need to update ... |
Contributor
Author
|
@pan3793 Agree with that. I'll handle it right away |
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
2 participants
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.
What
Resolves ZEPPELIN-6501. Rather than refreshing the hardcoded version numbers in
AGENTS.md, this removes the version literals and points each one to its source of truth, so the file cannot drift again.Changed spots: Project Overview (Language, Frontend, Version) and the Contributing → Prerequisites table (JDK, Maven, Node.js).
pom.xml(java.version,scala.binary.version)pom.xml<version>zeppelin-web-angular/package.json(engines.node,@angular/core); Node build pin inpom.xml(node.version).mvn/wrapper/maven-wrapper.properties(the./mvnwwrapper pins it)Why reference instead of updating the numbers
The listed values had already drifted — the frontend was documented as Angular 13 / Node 18 but is actually Angular 21 / Node ≥22.12. Simply bumping them to today's values would recreate the same problem at the next upgrade: a second copy that quietly goes stale (which is exactly why this issue exists).
AGENTS.mdis read primarily by AI coding agents (and new contributors). For that audience a single source of truth is worth more than the convenience of seeing the number inline on one page — an agent can openpackage.json/pom.xmlin one step, whereas a stale literal actively misleads it into wrong build instructions. So the doc now keeps the pointer and lets the canonical file own the value.Editorial guidance that is not itself a version literal is preserved (e.g. "use exactly that JDK major, not a newer/older one").
Notes
CLAUDE.mdis a symlink toAGENTS.md, so it is covered automatically.