docs: refactor AGENTS.md into an entry point, move build mechanics to CONTRIBUTING - #1045
Open
nielspardon wants to merge 1 commit into
Open
docs: refactor AGENTS.md into an entry point, move build mechanics to CONTRIBUTING#1045nielspardon wants to merge 1 commit into
nielspardon wants to merge 1 commit into
Conversation
… CONTRIBUTING Bring AGENTS.md in line with the AGENTS.md convention introduced for the spec repo in substrait-io/substrait#1117: a lean entry point plus the notes agents specifically need, with generally-applicable build and contribution mechanics living in the human-facing docs. - Restructure the AGENTS.md intro into a "Start here" pointer to README.md and CONTRIBUTING.md. - Add a "Keep PR descriptions high-signal" guideline: drop file lists, CI-verified-pass claims, and implicit process notes; keep commit bodies free of git trailers. - Move the build/test/format command reference, PMD tripwires, and the build-logic included-build note into a new CONTRIBUTING.md "Building and testing" section, and fold the JDK 17 daemon-consistency and GraalVM native-image details into its "Gradle & JDK 17" section. AGENTS.md keeps only the agent-specific verification workflow.
nielspardon
requested review from
andrew-coleman,
benbellick,
bestbeforetoday and
vbarua
July 29, 2026 12:49
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
1 participant
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.
Aligns this repo's
AGENTS.mdwith the ecosystem convention introduced for the spec repo in substrait-io/substrait#1117: a lean entry point plus the notes agents specifically need, with generally-applicable build and contribution mechanics living in the human-facing docs so there is a single source of truth.What changes
AGENTS.mdbecomes an entry point. The intro is now a "Start here" pointer toREADME.mdandCONTRIBUTING.mdrather than a standalone build guide.semantic-releasecommit message and feedCHANGELOG.md.CONTRIBUTING.md. The build/test/format command reference, PMD ruleset and tripwires, and thebuild-logicincluded-build note land in a new "Building and testing" section; the JDK 17 daemon-consistency and GraalVM native-image details fold into the existing "Gradle & JDK 17" section.AGENTS.mdkeeps only the agent-specific verification workflow (build-before-push, cross-module compile check).The codebase-specific architecture knowledge (module layout, Immutables/visitor/proto-converter patterns, Isthmus/Spark change-safety notes) stays in
AGENTS.md— it is this repo's equivalent of the spec PR's "what agents need to get right." No content was lost; the build mechanics were relocated, not removed.🤖 Generated with AI