From 57243c691d8a557320457fbcf718509e29ea2ee1 Mon Sep 17 00:00:00 2001 From: "John Paul E. Balandan, CPA" Date: Tue, 13 Oct 2026 16:34:23 +0800 Subject: [PATCH] chore: clarify the compatibility and static-analysis rules for agent reviewers --- .github/copilot-instructions.md | 11 ++++++-- .github/instructions/tests.instructions.md | 2 ++ AGENTS.md | 29 +++++++++++++++++++--- 3 files changed, 37 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4ad38ee3eadf..cd4aff6cff0a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -23,8 +23,15 @@ Prioritize actionable findings involving: ## Review behavior - Determine the PR base branch and apply the compatibility policy from - `AGENTS.md`. If the base branch cannot be determined, assume `develop` - and state that assumption. + `AGENTS.md`. When it is not visible, read it from the title prefix and + the labels as `AGENTS.md` describes, and otherwise assume `develop` and + state that assumption. +- Before reporting a compatibility break, confirm the symbol exists in the + latest tagged release. A symbol introduced on the base branch since that + release is unreleased and may change freely, as `AGENTS.md` describes. +- Do not report a PHPStan suppression or baseline entry covered by the + exceptions in `AGENTS.md`, or a missing reset of state that + `CIUnitTestCase::tearDown()` already restores. - Do not report formatting-only issues already enforced by PHP-CS-Fixer. - Every finding should identify a concrete failure scenario and the affected code. diff --git a/.github/instructions/tests.instructions.md b/.github/instructions/tests.instructions.md index af2d9a96ba96..63722474b723 100644 --- a/.github/instructions/tests.instructions.md +++ b/.github/instructions/tests.instructions.md @@ -14,6 +14,8 @@ applyTo: "tests/**/*.php" Avoid testing private implementation details. - Restore services, factories, environment variables, superglobals, handlers, locale, time-related state, and other global state modified by a test. + Check `CIUnitTestCase::tearDown()` first: a test need not repeat the + resets it already performs. - Tests must not depend on execution order or state left by another test. - Do not replace a meaningful assertion with a weaker assertion to make a test pass. diff --git a/AGENTS.md b/AGENTS.md index 208568025619..675c9f83e33e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,8 +19,13 @@ existing implementation before introducing a new abstraction or convention. ## Target branch and compatibility policy Compatibility is judged against the pull request's base branch, not the -contributor's source or feature branch. When the base branch is unknown, -apply the stricter `develop` policy. +contributor's source or feature branch. When the base branch is not stated, +take the cues from the title prefix and the labels. A `feat:` prefix and the +`enhancement`, `new feature`, `breaking change`, or `4.x` labels point to the +next minor branch. A `fix:`, `refactor:`, or `docs:` prefix and the `bug` or +`refactor` labels can go either way, since the next minor branch also takes +fixes to its own unreleased code, so look at what the change touches. When no +cue settles it, apply the stricter `develop` policy. ### Base branch `develop` @@ -50,6 +55,16 @@ complete the documented deprecation lifecycle. - Every accepted break needs tests for the new behavior, a minor-version changelog entry, and migration instructions in the upgrading guide. +### Unreleased API + +A symbol first added on the base branch after its latest tagged release is +unreleased. Nothing outside the repository can depend on it yet, so changing, +renaming, or removing it is not a compatibility break: it needs no +deprecation, no upgrading-guide entry, and no changelog line beyond the one +describing the final shape. Check the version tags or the changelog of the +unreleased version before reporting a break on such a symbol. The +compatibility policy applies to what the latest tagged release ships. + ### All base branches - Production code must run on PHP 8.2. Do not require a newer PHP version, @@ -83,7 +98,15 @@ complete the documented deprecation lifecycle. - Add PHPDoc only when it contributes information that native types cannot express. Do not duplicate a parent or interface docblock. - Never suppress a static-analysis error or update a baseline to make a - check pass. + check pass. The accepted exceptions are: + - a false positive, when the usage is judged correct; + - a suppression needed to assert a runtime behavior in a test; + - a call to a function mocked in `system/Test/Mock/MockCommon.php`, such + as `is_cli(false)`, which PHPStan reports as `arguments.count`. + + Regenerate the baseline with `composer phpstan:baseline`, never by editing + the `.neon` files, and add a test file that calls `is_cli()` with an + argument to the `RemoveExtraParametersRector` skip list in `rector.php`. ## FrankenPHP Worker Mode