docs: introduce a contributor guide for humans and AI coding tools#23195
Merged
enricobattocchi merged 17 commits intotrunkfrom Apr 28, 2026
Merged
docs: introduce a contributor guide for humans and AI coding tools#23195enricobattocchi merged 17 commits intotrunkfrom
enricobattocchi merged 17 commits intotrunkfrom
Conversation
Adopts the AGENTS.md convention (stewarded by the Agentic AI Foundation under the Linux Foundation) as the single source of truth for coding-agent and contributor instructions. AGENTS.md is recognised natively by ~20 AI coding tools including OpenAI Codex, Cursor, Aider, Zed, Copilot, Gemini CLI, Windsurf, and JetBrains Junie. CLAUDE.md becomes a thin pointer that uses Claude Code's @-include syntax to pull AGENTS.md into context, keeping one source of truth across tools. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- .cursor/rules/agents.mdc: always-applied Cursor rule that references AGENTS.md via @-include so Cursor users share the same context. - .github/copilot-instructions.md: tuned for Copilot's PR-review use case. Points at AGENTS.md / CONTRIBUTING.md / the PR template as authoritative sources, then lists review priorities (PR hygiene, tests/coverage, code style, safety, security) plus a 'what not to flag' list. Kept under the 4,000-character limit Copilot enforces on review instructions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove broken 2013 S3-hosted logo image. - Correct label name to 'patch welcome' (was 'patch-welcome'). - Replace outdated 'New issue template' phrasing with a reference to the GitHub issue forms picker. - Clarify that 'trunk' is the dev branch and 'main' tracks the latest released version. - Add pointer to the security program. - Replace the standalone link to the WordPress Coding Standards with a reference to Yoast Coding Standards (a WPCS superset). - Add a 'Supported environment' line (PHP 7.4+, latest two WP majors). - Add a pre-push checklist: composer test, composer check-branch-cs must report no new errors/warnings, composer lint-branch, yarn lint and yarn test for JS changes, plus guidance on composer test-wp-env. - Add a coverage paragraph: every PR should increase or hold coverage and explain in the PR body when it cannot. - Add a short 'Changelog entry and label' subsection pointing external contributors at the PR template for the full rules. - Flatten heading hierarchy and update stale help.github.com links. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Strengthens the commit-hygiene guidance in three places: - AGENTS.md: replaces the generic 'small, atomic commits are preferred' line with actionable guidance — what atomic means, when to split (unrelated changes), and when not to (closely coupled changes). - CONTRIBUTING.md: same guidance aimed at external contributors, in the pull-request opening checklist. - .github/copilot-instructions.md: adds a PR-hygiene bullet asking Copilot code review to suggest splitting when a PR mixes unrelated changes in a single commit. Kept under the 4000-character limit. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds explicit license-compatibility guidance so contributors (human and AI) can confirm their code is safe to submit under GPL-2.0-or-later: - CONTRIBUTING.md: new 'License and copyright' subsection listing the specific checks — own work or relicense-able, no incompatible sources (proprietary, GPL-3.0-only, CC with restrictions), attribution for reused compatible code, no code whose licensing is unclear (including AI-generated code whose terms have not been verified). - AGENTS.md: thin reminder section pointing at the CONTRIBUTING.md guidance. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Introduces a tool-agnostic procedure for opening a pull request that can be shared across Claude Code, Cursor, and any human contributor. - docs/workflows/create-pr.md: canonical procedure. Contains only process steps (gather context, verify checks, decide changelog bullets, fill template, create PR, self-check). Defers every rule — grammar, labels, bracket syntax, release-branch handling — to PULL_REQUEST_TEMPLATE.md / CONTRIBUTING.md / AGENTS.md so the rules live in one place each. - .cursor/rules/create-pr.mdc: auto-applied Cursor rule that loads the recipe via @-include when the user asks to open a pull request. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds guidance that applies to both issues and pull requests: keep the description focused on what the reviewer or triager actually needs, and do not pad sections to look thorough. - CONTRIBUTING.md: softens the 'include as much information as possible' bullet on issue reports to 'include everything needed, stay focused'. Adds a new step 8 on the PR-opening checklist asking for focused Context / Relevant technical choices / Test instructions and for links instead of restatements of linked issues or epics. - AGENTS.md: thin bullet mirroring the rule with a pointer tone. - .github/copilot-instructions.md: adds a PR-hygiene bullet asking Copilot code review to flag padded descriptions and restatements of linked issues/epics. Compresses the intro to stay under the 4000- character cap Copilot enforces on review instructions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Moves the content-based guidance (repository layout, code placement, dependency injection, build/test commands, testing policy, code style) out of AGENTS.md and into .github/CONTRIBUTING.md. AGENTS.md becomes a thin 'agent delta' that lists only the behaviours specific to AI coding tools, pointing back at CONTRIBUTING.md for everything else. The net effect: - CONTRIBUTING.md now has seven new subsections under 'I want to create a patch': Repository layout, Where to put new code (with Onion dependency rules and Legacy folders subsections), Dependency injection, PHP workflow, JavaScript workflow, Testing, Code style. It also gains a branch-naming convention bullet in step 1 of 'Opening a pull request'. - AGENTS.md shrinks from 148 lines to 27: a short intro plus a list of agent-specific behaviours (delegate long-running commands, verify before recommending, ask don't guess, prefer editing, don't paper over failures, respect creator/merger split, never hand-edit generated files, default to CONTRIBUTING.md). - Both files agree on which one wins when they appear to contradict: CONTRIBUTING.md is authoritative for content, AGENTS.md only for agent behaviour. No information was lost — every rule still lives in exactly one place. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follows the canonical-source-of-truth split introduced in the previous commit: CONTRIBUTING.md is the primary contributor doc, AGENTS.md is the agent-behaviour delta. - CLAUDE.md: now pulls CONTRIBUTING.md into context first, then AGENTS.md on top, via the @-include syntax. - .cursor/rules/agents.mdc: same — CONTRIBUTING.md is primary, AGENTS.md layers the agent delta. - .github/copilot-instructions.md: reorders the authoritative list so CONTRIBUTING.md and PULL_REQUEST_TEMPLATE.md come first, AGENTS.md is described as an agent-behaviour supplement. Intro line tightened to keep the file under Copilot's 4000-character cap. - docs/workflows/create-pr.md: consolidates the 'where rules live' pointers. Content rules (architecture, tooling, testing, commits, branches, pre-push) now all point to CONTRIBUTING.md; AGENTS.md only covers agent-behaviour rules. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a collapsed-link TOC at the top of CONTRIBUTING.md so readers can jump directly to the relevant section. The file now covers three distinct flows — reporting issues, developing against the plugin, and opening PRs — and the TOC makes that easier to navigate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Dependency injection section in CONTRIBUTING.md (and a matching
Copilot review bullet) previously instructed contributors to commit
the regenerated src/generated/container.php and .meta. That was
wrong: /src/generated/ is gitignored (.gitignore:88) and has never
been tracked. composer install / update run compile-di via the
post-autoload-dump hook, so local dev, CI, and the release build
each regenerate it fresh. The compiled container does end up in the
shipped release artifact — just not in the Git history.
- CONTRIBUTING.md Repository-layout table: note that src/generated/
is gitignored and bundled into the release artifact by the build
pipeline.
- CONTRIBUTING.md Dependency-injection section: replace the
'commit the regenerated files' bullet with the correct guidance
(do not commit; every environment rebuilds). Rewrite the
'CI complains' bullet to describe the actual failure mode:
DI-compilation failure due to unresolvable auto-wiring, not a
committed-container-out-of-sync situation.
- .github/copilot-instructions.md: drop the Code-style bullet that
required a committed container.php. Reword the Safety bullet from
descriptive ('Never hand-edited: ...') to action-oriented ('Flag
any file under these paths in the diff — gitignored; must not be
committed') so Copilot knows what to do when it sees one.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The docs were prescribing a specific bugfix pattern
('Fixes a bug where … (was …) when …') that the PR template only
presents as an example. The template explicitly allows either
'happened when …' or 'was caused by …' phrasings, and stipulates
only the substantive rules: past tense, incorrect behaviour
followed by the triggering condition, no hypothetical or nested
conditionals.
The rigid phrasing also contradicted the 'don't flag minor
changelog wording variations' guidance in the same Copilot file.
- CONTRIBUTING.md Changelog entry section: restate the real rules
(past tense, behaviour-then-condition, no hypotheticals) and show
both accepted phrasings. Point to PULL_REQUEST_TEMPLATE.md as the
full authority.
- .github/copilot-instructions.md PR-hygiene bullet: trim to the
substantive rules; rely on the existing 'What NOT to flag' entry
for wording-variation tolerance.
- docs/workflows/create-pr.md self-check bullet: reference the PR
template's grammar rules instead of a rigid pattern string.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
svn-assets/ holds the wordpress.org plugin-directory assets (banners, icons, screenshots). It is tracked in Git and hand-maintained, not generated or gitignored, so it does not belong in the same list as build/, vendor/, node_modules/, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The release artifact pipeline re-runs grunt build:images (imagemin) during create-rc / create-beta / artifact. If the committed images aren't already optimised, the release build fails. Make this explicit in the contributor guide, the create-pr self-check, AGENTS.md, and the Copilot review checklist, so both humans and AI tools catch it before the PR is opened. Also fix the matching PR-template checkbox: a "commited" typo and narrow "introduces new images" wording that didn't cover edits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
enricobattocchi
added
the
changelog: non-user-facing
Add an explicit conciseness rule for changelog bullets (one short sentence, no colon- or semicolon-chained clauses) across CONTRIBUTING.md, the PR template, AGENTS.md, the create-pr self-check, and the Copilot review checklist. At the same time, drop Context / Relevant technical choices conciseness from the Copilot flag list and soften the matching CONTRIBUTING.md paragraph — brevity there is welcome but not enforced. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
enricobattocchi
changed the title
Non-user-facing PRs (documentation, pure refactors, internal tooling) don't need QA verification at RC time — QA checks user-visible behaviour. Make this explicit in the PR-template HTML comment and in the create-pr workflow step, so future authors don't fabricate QA steps for PRs where there is nothing for QA to check. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diedexx
approved these changes
Apr 28, 2026
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
enricobattocchi
added
changelog: other
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.
Context
Summary
This PR can be summarized in the following changelog entry:
Relevant technical choices:
AGENTS.md,.cursor/rules/*.mdc,.github/copilot-instructions.md,CLAUDE.md, and the Claude Codecreate-prskill all reference it rather than duplicating rules. Edits to rules land in CONTRIBUTING.md (or the PR template) so every tool picks them up.composer test,test-wp-env,check-branch-cs,lint-branch,yarn lint,yarn test,grunt build:images) were not run: the diff contains only Markdown and.mdcfiles — no PHP, JS, CSS, images, or other runtime code.Test instructions
Test instructions for the acceptance test before the PR gets merged
This PR can be acceptance tested by following these steps:
.github/CONTRIBUTING.mdand read through it section by section; confirm the table of contents and all intra-repo links (toAGENTS.md,PULL_REQUEST_TEMPLATE.md,docs/workflows/create-pr.md,license.txt,src/README.md) resolve.AGENTS.mdand confirm it reads as a short agent-behaviour delta that points back at CONTRIBUTING.md.docs/workflows/create-pr.mdand walk through the PR-creation procedure end to end..github/copilot-instructions.mdand confirm the review-priority sections are coherent as Copilot review guidance..cursor/rules/agents.mdcand.cursor/rules/create-pr.mdcand confirm the@../../…include directives reference the expected files.CLAUDE.mdat the repo root and confirm the two@includes point at CONTRIBUTING.md and AGENTS.md..github/PULL_REQUEST_TEMPLATE.mdand confirm the Quality-assurance checkbox aboutgrunt build:imagesreads "committed" (not "commited") and covers both new and edited images.Relevant test scenarios
Test instructions for QA when the code is in the RC
QA can test this PR by following these steps:
Impact check
This PR affects the following parts of the plugin, which may require extra testing:
Other environments
[shopify-seo], added test instructions for Shopify and attached theShopifylabel to this PR.[yoast-doc-extension], added test instructions for Yoast SEO for Google Docs and attached theGoogle Docs Add-onlabel to this PR.Documentation
Quality assurance
grunt build:imagesand committed the results, if my PR introduces or edits images or SVGs.Innovation
innovationlabel.Fixes #