docs: tighten AGENTS.md rules for directory listings, branch names, and PR template#21005
Conversation
…nd PR template - Mark the Project Overview directory tree as the canonical map and require updates in the same commit when directories are added, renamed, or removed (CI does not catch drift). - Add a required Branch name section: branches must use the PR change-type prefix (fix, feat, refactor, perf, test, chore, ci, build, style, revert, docs) instead of agent/tool prefixes such as 'claude/'. - Strengthen the Pull request body section with explicit anti-patterns (Summary/Test plan substitution, omitting Use of AI, dropping HTML comment hints) so the org-wide template stops being skipped.
Add an 'After opening the PR — wait for Copilot review' subsection under Git Commit & Pull Request. It mandates subscribing to the PR after opening it, addressing every Copilot comment (fix or reasoned reply, never silent ignore), and only unsubscribing once all comments are handled and CI is green.
- Add lib/typescript/ (experimental TypeScript module support). - Add test/hotPlayground/ (hand-written HMR playground fixtures). - List the auto-generated declarations/ directory both in the Project Overview tree and in the Auto-generated files section.
Move the 'this is not optional, reviewers have flagged this being skipped, read it in full every time' warning from the Pull request body section up into 'Conventions in this guide', so it applies to every REQUIRED section instead of only the PR body.
Make explicit that the wait-for-Copilot loop covers not only the initial create_pull_request but every push to the PR branch: Copilot re-reviews after each new commit, and the agent must wait and address those new comments the same way as the first review. The loop only terminates when Copilot's latest review has zero outstanding threads.
Add guidance to the 'Adding a Changeset' section: keep the description to a single imperative sentence, ideally ≤ 80 characters. Changesets concatenate into the release CHANGELOG.md verbatim, so rationale, migration notes, and links belong in the PR body — not in the changeset file.
|
|
This PR is packaged and the instant preview is available (6c5f2f8). Install it locally:
npm i -D webpack@https://pkg.pr.new/webpack@6c5f2f8
yarn add -D webpack@https://pkg.pr.new/webpack@6c5f2f8
pnpm add -D webpack@https://pkg.pr.new/webpack@6c5f2f8 |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #21005 +/- ##
=======================================
Coverage 90.94% 90.94%
=======================================
Files 573 573
Lines 58986 58986
Branches 15898 15898
=======================================
Hits 53647 53647
Misses 5339 5339
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR updates AGENTS.md to make contributor/agent workflow guidance stricter and more enforceable, particularly around keeping repository directory maps in sync, standardizing branch naming, and preventing drift from the org-wide PR body template.
Changes:
- Marks the “Project Overview” directory listings as canonical and requires updating them when top-level directories change.
- Adds a REQUIRED branch naming convention based on the PR template’s change-type list.
- Expands REQUIRED PR-body guidance with explicitly PR-blocking anti-patterns and adds a REQUIRED step to wait for and address GitHub Copilot review feedback.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - Writing `## Summary` and `## Test plan` headings instead of the bold-labelled sections below (`**Summary**`, `**What kind of change does this PR introduce?**`, …). | ||
| - Omitting **Use of AI** — this is mandatory under the [webpack AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md); a missing or vague answer can get the PR closed. | ||
| - Omitting **What kind of change does this PR introduce?** or answering with something outside the allowed list (`fix`, `feat`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `style`, `revert`, `docs`). The answer here must also match the branch-name prefix (see [Branch name](#branch-name)). |
Merging this PR will improve performance by 21.23%
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing 
Footnotes
|
AGENTS.md (after #21005) caps changeset descriptions at one sentence ≤ 80 characters in the imperative — multi-paragraph rationale belongs in the PR body, not the changeset.
AGENTS.md (after #21005) caps changeset descriptions at one sentence ≤ 80 characters in the imperative — multi-paragraph rationale belongs in the PR body, not the changeset.
AGENTS.md (after #21005) caps changeset descriptions at one sentence ≤ 80 characters in the imperative — multi-paragraph rationale belongs in the PR body, not the changeset.
require updates in the same commit when directories are added,
renamed, or removed (CI does not catch drift).
change-type prefix (fix, feat, refactor, perf, test, chore, ci,
build, style, revert, docs) instead of agent/tool prefixes such
as 'claude/'.
(Summary/Test plan substitution, omitting Use of AI, dropping HTML
comment hints) so the org-wide template stops being skipped.