[doc] AGENTS.md: add XQSuite-vs-Java test-selection rubric; remove stale Known Issues - #6483
Merged
Merged
Conversation
Adds a "Choosing XQSuite vs Java tests" subsection to the testing conventions: default to XQSuite for XQuery-level behavior, and reach for Java only when XQSuite structurally can't express or exercise the behavior (pure-Java units, request/ response/session context that needs a live HTTP request, the HTTP/transport layer itself, or Java-level wiring such as broker pool / locking / transactions). Within Java, use the lightest vehicle that exercises the real behavior. Cites the request-module content-negotiation work (eXist-db#6477) as precedent. AGENTS.md is the canonical, repo-rooted home for this guidance so it is visible to sessions regardless of which repo they are rooted in. Also removes the "Known Issues" section, whose three entries were all stale; two were never true: - groupby.collation "flaky" / ArrayIndexOutOfBoundsException: unsubstantiated. No issue, PR, commit, or CI evidence backs it; the test is deterministic and passes. Asserting an unbacked "known flake" risks agents dismissing real CI failures. - fn:filter / issue eXist-db#3382: fixed. eXist-db#3382 is closed and fn:filter now raises XPTY0004 when the predicate function does not return xs:boolean. - fn:doc() file:// restriction: unsubstantiated. DocUtils already routed file:/URL paths through SourceFactory when this entry was added (2026-03-15), so fn:doc could load file: documents all along; the later eXist-db#6207 work only added security-gating, it did not lift a block that never existed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
duncdrum
approved these changes
Jun 15, 2026
line-o
approved these changes
Jun 15, 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
3 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.
[This PR was co-authored with Claude Code. -Joe]
Summary
Two documentation-only changes to
AGENTS.md:Why
AGENTS.mdis the canonical, repo-rooted home for contributor conventions, so guidance placed here is visible to any session or contributor working in the repo. The rubric captures a recurring decision (XQSuite vs Java, and which Java vehicle) that otherwise gets re-derived case by case. The Known Issues section, meanwhile, had drifted out of date and was actively misleading.The test-selection rubric
%test:annotations) for XQuery-level behavior.request:/response:/session:throwXPDY0002with no live request); behavior that is the HTTP/transport layer; or behavior depending on Java-level wiring (broker pool, locking, transactions, startup/config).Why the Known Issues section was removed
All three entries were verified against current
developand found stale:groupby.collation"flaky" /ArrayIndexOutOfBoundsException— unsubstantiated. No issue, PR, commit, or CI log backs the claim; it entered via a bulk doc-add commit with no linked bug. The test is deterministic (fixed expected result, codepoint collation) and passes. Leaving an unbacked "known flake" in the guide risks agents dismissing real CI failures as expected.fn:filternow raisesXPTY0004when the predicate function does not returnxs:boolean.file://restriction — unsubstantiated.DocUtilsalready routedfile:/URL paths throughSourceFactorywhen this entry was added (2026-03-15), sofn:doccould loadfile:documents all along. The later Fix XQuery 3.1 compliance: casting, error codes, fn:not, path dedup, format-date, and more #6207 work only added security-gating (e.g. an absolutefile:///etc/passwdis blocked there) — it did not lift a block that never existed.Two of the three were never true, and the third is fixed, so the section is removed rather than left partially correct.
Notes
Documentation only — no code or test changes.