blob: eab15774eb557f3e0bed73935f369a00f7f5e4ea [file] [view]
---
trigger: model_decision
description: rules to apply to pull request descriptions
---
@CONTRIBUTING.md
# Pull Request Conventions
Before drafting any pull request description, strictly adhere to the rules in
`CONTRIBUTING.md` above.
## Prevent Agent Oversight of `CONTRIBUTING.md`
* Always include `@CONTRIBUTING.md` in rule definitions so that PR formatting
rules are injected into context whenever PR workflows run.
## Commit & PR Types
* `fix:` / `feat:`: User-visible changes ONLY.
* `build:` / `build(release):`: Internal release tooling
(`dev/release/`), developer workflows, and build scripts. Always
prefer `build(release):` over `chore:` or `chore(release):`.
* `docs:`: Documentation and issue templates (`.github/ISSUE_TEMPLATE/`).
* `ci:`: `.bazelci` and Buildkite CI configurations.
* `workflow:` / `workflows:`: GitHub Actions workflow configurations
(`.github/workflows/`).
* `tests:`: Test-only changes and test-helper fixes (never `fix:` or
`fix(tests):`).
* `agents:` / `agents(<scope>):`: Agent rules, skills, and prompts
(`.agents/`).
* `refactor:`: Internal refactoring and fixes for unreleased changes. Never use
`fix:` or `feat:` unless modifying released, user-visible behavior.
## PR Commit Workflow Invariant
* Once a Pull Request is created, always make new commits or merge commits.
* **NEVER** amend or rebase commits on an active PR branch to avoid breaking
code review threads.
* **PR Metadata Discrepancies**: If a PR title or description diverges from
the branch's actual scope, notify the user of the discrepancy and ask for
confirmation before updating GitHub.
* **NEVER** include a list of per-file edits, changelog bullet points of
individual file modifications, test execution logs/checklists, or AI
disclosure metadata in PR descriptions or commit messages.
* **AI Disclosure & Comment Etiquette**: Keep the PR description clean for use
as the merge commit message. Only when initially creating a new PR, post a
separate comment so maintainers understand who/what they are interacting
with: explain how comments on the PR will be handled (whether an agent
autonomously monitors and replies, whether a human reviews/approves agent
responses before posting, or whether the human responds directly). Do not
post a standalone AI disclosure comment when merely pushing commits to an
existing PR (such as a Dependabot PR); instead, disclose AI authorship only
on comments you actually post (see below). Never post comments for every CI
run or narrate build IDs, commit SHAs, line counts, or trivial diff details
(e.g., "comment-only"); comment `PTAL` only when ready for re-review.
* High-level overview only: state *why* the change is made and *how* at a
conceptual level. Link related issues (e.g. `Work towards #<issue>`).
* **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear,
active, and direct phrasing for *why* and *how*.
* **Preserve Existing Descriptions**: Preserve the author's wording unless
instructed to change it. Wrap bodies at 72 columns.
* **Open Questions & Follow-Up Items**:
* Add the `"do not merge"` label to the PR when the PR description contains
open questions (e.g., `gh pr edit <pr> --repo bazel-contrib/rules_python
--add-label "do not merge"`).
* During code review, inspect the PR description and comments for open
questions, `TODO` items, or "Things we could do / follow-up" notes.
Evaluate each item against the diff and project rules, flag unresolved
items with `BLOCKER`, `QUESTION`, or `HUMAN-SIGN-OFF`, and verify the
`"do not merge"` label is applied if open questions remain.
## PR Review Comments & Thread Resolution
* End every posted PR comment or review reply with an italicized disclosure
line:
* If the exact comment text was not shown to and approved by the user before
posting (including automatic PR AI disclosure comments):
`*This is an automatically generated agent comment.*`
* Only if the user was shown the exact comment text and explicitly approved
posting it:
`*This is an agent-generated comment reviewed and approved by the user.*`
* After fixing an inline PR review thread, reply with the commit hash and
explanation (`addPullRequestReviewThreadReply`) and resolve the thread
(`resolveReviewThread`) via `gh api graphql`, batching at most 3-4 threads per
request to avoid `502 Bad Gateway` timeouts.