diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 9ba0b64c850b..e7b34364d1fb 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -40,4 +40,4 @@ Task-specific guides live in `.ai/skills/` and are loaded on demand by AI agents ## Self-review before a PR -Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. +Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. Share the final report on the PR (description or comment) — see the skill for details. diff --git a/.ai/review-rules.md b/.ai/review-rules.md index c936082dcce5..32a55662b925 100644 --- a/.ai/review-rules.md +++ b/.ai/review-rules.md @@ -20,7 +20,7 @@ Common mistakes are covered in the common-mistakes / gotcha sections in [AGENTS. A PR can leave existing docs stale or surface a pattern worth recording. Scan the docs related to what the PR touches and flag updates as a **suggestions / additional info** section (not blocking): - **Usage docs.** New or changed public behavior — a new pipeline/model, a new argument, changed defaults, a renamed API — should have matching updates in `docs/`, docstrings, and examples. Flag any that now describe outdated behavior or that are missing for the new surface. -- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake. +- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake. Human review comments on the PR are a good source for these: if a human reviewer pointed something out and your review missed it, that usually indicates a doc gap — figure out what's missing and propose the addition. ## Dead code analysis (new models) diff --git a/.ai/skills/self-review/SKILL.md b/.ai/skills/self-review/SKILL.md index cfc45e54ebb0..2114c91f887b 100644 --- a/.ai/skills/self-review/SKILL.md +++ b/.ai/skills/self-review/SKILL.md @@ -14,7 +14,8 @@ Runs the same rubric as the `@claude` CI reviewer, so you catch issues before a maintainer does — but over your **whole** PR diff. (The CI scopes itself to `src/diffusers/` and `.ai/`; for your own PR, also review your tests, docs, and scripts.) You're already on the branch with the conventions loaded, so: get the -diff → review it against the rubric → report. +diff → review it against the rubric → report → iterate with the contributor +until it's ready, then remind them to share the final notes on the PR. ## 1. Get the diff @@ -46,3 +47,13 @@ touched, also read `.ai/models.md`, `.ai/pipelines.md`, or `.ai/modular.md`. Report only — do not edit files. Be concrete, cite the rule, review the whole diff, and don't invent issues or flag pure style. + +## 4. Iterate until ready, then share + +Expect several rounds: the contributor addresses findings, you review again. +Keep working with them to fix as much as possible until the verdict is +**READY** — the **Leave for the actual review** items are the only ones that +should reach the reviewer unresolved. End the final round's report by +reminding the contributor to share it on the PR (description or a comment) — +it saves the reviewer a few rounds of back-and-forth. Never commit the notes as +part of the diff. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 55b148b0c10e..e28a3cb96563 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,6 +7,8 @@ Once merged, your PR is going to appear in the release notes with the title you Then, please replace this with a description of the change and which issue is fixed (if applicable). Please also include relevant motivation and context. List any dependencies (if any) that are required for this change. +If you used an AI agent, also include your final self-review notes here (or post them as a comment) — the report from the last self-review round, including any findings you intentionally did not fix and why. See https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md + Once you're done, someone will review your PR shortly (see the section "Who can review?" below to tag some potential reviewers). They may suggest changes to make the code even better. If no one reviewed your PR after a week has passed, don't hesitate to post a new comment @-mentioning the same persons---sometimes notifications get lost. --> @@ -18,7 +20,8 @@ Fixes # (issue) ## Before submitting - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so: - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide? - - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)? + - [ ] Did you run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill on the diff? + - [ ] Did you share the final self-review notes in the PR description or a comment? - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)? - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs) - [ ] Was this discussed/approved via a GitHub issue or the [forum](https://discuss.huggingface.co/c/discussion-related-to-httpsgithubcomhuggingfacediffusers/63)? Please add a link to it if that's the case. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index c332792fd3d0..7f7d8bd77f29 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -593,7 +593,9 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Coordinate before opening a PR.** Find or open an issue, review similar PRs (open and recently closed), and wait for an explicit acknowledgment from a maintainer on that issue before opening a PR. This gives us a chance to discuss scope, avoid duplicate work, and confirm the approach. - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. -- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — just add a brief note in the PR description for anything you intentionally skipped, so the reviewer knows it was a deliberate call. +- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill — it reviews your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md), the same rubric the `@claude` CI reviewer uses — and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. +- **Share your self-review notes.** Please post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. It helps the reviewer see what has already been checked and which calls were deliberate, and usually saves a few rounds of back-and-forth. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). + - Your **self-review notes** (or a link to the PR comment containing them), as described above.