docs(agents): align AGENTS.md to Java 11 reality#2947
Merged
Conversation
Problem: AGENTS.md claimed Java 11 source compatibility but
still banned Java 9-11 language features (`var`, `List.of()`,
`Optional.isEmpty()`, `String.isBlank()`, etc.) in its
banned-patterns table. The SDKMAN section also told agents to
install and use Java 8 ("required for uPortal-start"), which
no longer matches reality — uPortal-start also moved to Java 11.
This left readers with two contradictory answers about what
Java version applies.
Goal: have the banned-patterns table, checklist, boundaries,
and SDKMAN guidance all reflect the real ceiling: Java 11 is
allowed in full, Java 12+ is off-limits; JUnit 4 remains the
test stack; uPortal-start runs on Java 11.
Changes:
- Banned-patterns table: drop `var`, `List.of()`/`Map.of()`,
`Optional.isEmpty()`, `String.isBlank()` (all Java 9–11,
now allowed). Expand the Java 12+ row into explicit rows
per feature: switch expressions with `->`, text blocks,
records, pattern matching for `instanceof`/`switch`, sealed
classes. Keep the JUnit 5 / inline-versions / commons-logging
bans unchanged.
- Add a lead-in sentence above the table stating that the ban
line is Java 12 and later.
- Checklist: "No Java 9+ language features or APIs used"
→ "No Java 12+ ..."
- Boundaries: same rewording.
- SDKMAN section: install/switch/default commands updated
from `8.0.472-amzn` to `11.0.30-amzn`. Prose updated to say
both uPortal and uPortal-start require Java 11. Added a
note pointing at the `.sdkmanrc` in each repo and
`sdk env`.
- Troubleshooting table: Java-version-mismatch fix command
updated to `sdk use java 11.0.30-amzn`.
Notes: no code changes; this is purely documentation
alignment. Spot-checked grep for remaining "Java 8" / "8.0."
references — all gone.
ChristianMurphy
approved these changes
Apr 24, 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
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.
Summary
AGENTS.mdhad two pieces of outdated guidance that contradicted the project's actual Java 11 stance:Banned-patterns table still flagged Java 9–11 features as banned (
var,List.of()/Map.of(),Optional.isEmpty(),String.isBlank()), even though the file's own tech-stack section says "sourceCompatibility 11". Since uPortal compiles under Java 11, those features are allowed.SDKMAN section told agents to install and use
java 8.0.472-amzn, annotated as "required for uPortal-start". uPortal-start also moved to Java 11, so that guidance sends agents down a broken path.Changes
All documentation — no code changes.
Banned-patterns table — the ban line shifts from "Java 9+" to "Java 12+"
Dropped rows for features allowed on Java 11:
varList.of(),Map.of()Optional.isEmpty()String.isBlank()Replaced the single "Records, text blocks, sealed classes" row with explicit per-feature rows, each annotated with the Java version that introduced it:
->(Java 14+)"""..."""(Java 15+)instanceof(Java 16+)non-sealed/permits(Java 17+)switch(Java 21+)Kept unchanged: JUnit 5 annotations, inline Gradle versions,
commons-logging.Added a short lead-in above the table clarifying that Java 9–11 features are fair game and the ban line is Java 12.
Checklist + Boundaries
"No Java 9+ language features or APIs used" → "No Java 12+ ..." (both occurrences).
SDKMAN section
8.0.472-amzn→11.0.30-amznin the install / switch / default example commands, and in the troubleshooting table's "Java version mismatch" fix line. Updated the prose to say both uPortal and uPortal-start require Java 11, and added a note about the.sdkmanrc+sdk envin each repo.Test plan
grep "Java 8\|8\.0\." AGENTS.md— no stale refs remain🤖 Generated with Claude Code