Repository navigation
docs: make test readability requirements explicit - #810
Merged
Merged
Conversation
gabotechs
approved these changes
Oct 28, 2026
gabotechs
added a commit
that referenced
this pull request
Oct 30, 2026
## Summary The Deploy Documentation workflow has been failing on every push to `main` since #810. That PR added a relative link to `../../../AGENTS.md` in `docs/source/contributor-guide/03-tests.md`. The link points outside the Sphinx source tree, so MyST emits a `myst.xref_missing` warning, and the build fails because warnings are treated as errors: ``` docs/source/contributor-guide/03-tests.md:61: WARNING: Unknown source document '.../AGENTS' [myst.xref_missing] ``` This replaces it with the absolute GitHub URL. The other contributor-guide pages already link this way to repo files outside `docs/`, such as the benchmarks README. ## Validation `make html` in `docs/` with `docs/requirements.txt` installed: `build succeeded.`, no warnings. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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.
Tests have repeatedly hidden their configuration or expected behavior behind helpers, loops, and separate snapshot files. Add concrete test-design rules to
AGENTS.md: make scenarios readable in place, share infrastructure without hiding intent, exercise public behavior, and keep coverage focused.Align the Iceberg and contributor testing guides so their advice to keep tests small does not encourage hiding the scenario. Prefer existing configuration hooks and compact inline snapshots, while allowing fixture loops, focused unit tests, and external snapshots when appropriate.
The rules synthesize recurring review feedback:
Validation:
git diff --check; verified relative links and the target heading. Documentation only; no runtime tests run.Developed with AI assistance.