docs: add Commit and PR Format section to AGENTS.md#26070
Open
He-Pin wants to merge 1 commit into
Open
Conversation
Motivation: AGENTS.md previously had no guidance on commit message bodies or PR descriptions, so LLM-assisted contributions tended to drift from the project's existing PR template and LLM policy. Modification: Add a "Commit and PR Format" section that defers to CONTRIBUTING.md, LLM_POLICY.md, and .github/pull_request_template.md, and provides: - a Motivation/Modification/Result/Tests/References commit-body shape, - explicit rules for the Tests and References footers, - a checklist for the PR body that mirrors the existing template. Also note that unrelated community-build submodule pointer drift must not be staged. Result: Agents and contributors have a single, scoped reference for commit and PR shape that does not duplicate or conflict with the authoritative docs. Tests: - Not run - docs only References: None - documentation improvement to AGENTS.md
bracevac
requested changes
May 18, 2026
| - Pick exactly one testing line (new tests, covered by existing tests, non-code, or manual with detail). | ||
| - Bug-fix PRs should add a regression test that fails before the fix. | ||
| - Behavior, public API, language, or operator-visible changes must update the matching docs under `docs/_docs/`. | ||
| - Scala and Java DSL changes must keep API, docs, and tests in parity. |
Contributor
There was a problem hiding this comment.
What are examples of "Scala DSL" respectively "Java DSL"?
| Follow `.github/pull_request_template.md` verbatim. In particular: | ||
|
|
||
| - Start the PR description with `Fixes #XYZ`, or explain why no issue exists. | ||
| - Pick exactly one LLM-usage line (`Extensively`, `Moderately`, `Minimally`, `Not at all`) per `LLM_POLICY.md`. |
Contributor
There was a problem hiding this comment.
I'm somewhat conflicted about this, because it sends the wrong signal. We are on the slippery slope to encourage more AI slop. A contributor is supposed to reflect on their changes and put thought into their PRs. Our stance should remain that this should be done manually.
I'm of course aware that this wouldn't prevent anyone from letting the agent fill it in for them. But at least it makes clear where we stand, and we'll use that against pure slop posters.
| Fixes #1234, Refs #1234, or `None - <short context>` | ||
| ``` | ||
|
|
||
| - Never omit `Tests`. Use `Not run - docs only` for documentation-only commits. Record any required tool that was missing (e.g. `scalafmt: not installed - skipped`). |
Contributor
There was a problem hiding this comment.
What if I make non-code changes? E.g., docs?
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.
How much have you relied on LLM-based tools in this contribution?
Moderately, for drafting the new section text from the existing project conventions (CONTRIBUTING.md, LLM_POLICY.md, .github/pull_request_template.md) and recent commit history. All wording was reviewed and edited by hand.
How was the solution tested?
Non-code change, no tests needed
Motivation
AGENTS.mdcurrently has no guidance on commit message bodies or PR descriptions, so LLM-assisted contributions tend to drift from the project's existing PR template and LLM policy.Modification
Add a "Commit and PR Format" section to
AGENTS.mdthat:CONTRIBUTING.md,LLM_POLICY.md, and.github/pull_request_template.mdas authoritative.Motivation/Modification/Result/Tests/Referencescommit-body shape, with explicit rules for theTestsandReferencesfooters.community-build/submodule pointer drift must not be staged.Result
Agents and contributors have a single scoped reference for commit and PR shape that does not duplicate or conflict with the authoritative docs.
Tests
References
None - documentation improvement to
AGENTS.md