You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/08/17 20:44:07 UTC
(magpie) branch main updated: docs(projects): add Magpie's own pr-management-code-review criteria (#1042)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new 15ab3539 docs(projects): add Magpie's own pr-management-code-review criteria (#1042)
15ab3539 is described below
commit 15ab3539c160912513e517b4600d3cad1ecc7ee0
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Mon Aug 17 22:44:00 2026 +0200
docs(projects): add Magpie's own pr-management-code-review criteria (#1042)
`pr-management-code-review` resolves its rule sources from
`<project-config>/pr-management-code-review-criteria.md`, but Magpie —
which self-adopts the framework — never carried that file. Only
`projects/_template/` had it, so running the skill against apache/magpie
silently fell back to a smaller default rule set instead of the project's
own rules. Found while running a review pass over the open-PR queue.
This is a navigation map, not a rule set: every row points at a section
that already exists in AGENTS.md, PRINCIPLES.md, CONTRIBUTING.md, or
docs/editorial-guidelines.md, so the skill can quote the source rule
verbatim. No rule text is duplicated and nothing moves out of AGENTS.md —
per the framework's own guidance that summaries drift while links do not.
Notable choices:
- Architecture-boundary and generated-file findings route to the
numbered PRINCIPLES entries (§12 project-agnosticism, §13
snapshot-plus-override) since that is where those rules live.
- Categories that do not apply to this repository (database/query
correctness, UI React/TypeScript) have no row: Magpie ships neither a
database layer nor a UI, so a finding in either category would be a
mis-classification rather than something to link.
- A Magpie-specific block adds the categories this repo's reviews
actually need — placeholder convention, external-content-as-data,
privacy-LLM routing, labelling, vendor neutrality, and the
inline-comment review default.
- Backports are recorded as not applicable: Magpie releases from a
single `main` and keeps no release-train branches.
Every link and `#anchor` is verified — lychee and markdownlint pass, and
the full `prek run --all-files` suite is green.
Generated-by: Claude Code (Opus 5)
---
.../magpie/pr-management-code-review-criteria.md | 125 +++++++++++++++++++++
1 file changed, 125 insertions(+)
diff --git a/projects/magpie/pr-management-code-review-criteria.md b/projects/magpie/pr-management-code-review-criteria.md
new file mode 100644
index 00000000..b3f8db6b
--- /dev/null
+++ b/projects/magpie/pr-management-code-review-criteria.md
@@ -0,0 +1,125 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Apache Magpie — pr-management-code-review criteria](#apache-magpie--pr-management-code-review-criteria)
+ - [Repo-wide source files](#repo-wide-source-files)
+ - [Per-area source files](#per-area-source-files)
+ - [Security-model calibration](#security-model-calibration)
+ - [Backports / version-specific PRs](#backports--version-specific-prs)
+ - [Section anchors](#section-anchors)
+ - [Magpie-specific sections](#magpie-specific-sections)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Apache Magpie — pr-management-code-review criteria
+
+Magpie's **own** review criteria map (Magpie self-adopts the framework —
+see [`.apache-magpie.lock`](../../.apache-magpie.lock)). This is the live
+config the
+[`pr-management-code-review`](../../skills/pr-management-code-review/SKILL.md)
+skill reads when reviewing a PR against `apache/magpie` itself, not a
+scaffold. The adopter template lives at
+[`projects/_template/pr-management-code-review-criteria.md`](../_template/pr-management-code-review-criteria.md);
+this file is that template filled with Magpie's values.
+
+This file is a **navigation map, not a rule set**. Magpie's review rules
+already live in [`AGENTS.md`](../../AGENTS.md),
+[`PRINCIPLES.md`](../../PRINCIPLES.md), and
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md); the rows below point at those
+sections so the skill can quote the source rule verbatim. Per
+[`criteria.md`](../../skills/pr-management-code-review/criteria.md), if you
+find yourself wanting to summarise a rule here, link to its section
+instead — summaries drift, links don't.
+
+## Repo-wide source files
+
+These apply to every PR regardless of which subtree it touches.
+
+| File | What it covers | Notes |
+|---|---|---|
+| [`AGENTS.md`](../../AGENTS.md) | The primary rule set: commit and PR conventions, the placeholder convention, external-content-as-data, documentation editorial rules, eval/mode-economics sync, and the pre-submit checklist. | Magpie has no `.github/instructions/code-review.instructions.md`; `AGENTS.md` is the single repo-wide source. |
+| [`PRINCIPLES.md`](../../PRINCIPLES.md) | The nineteen governing principles — architecture boundaries (project-agnosticism, snapshot-plus-override), vendor neutrality, deterministic gates, eval as a release blocker, licensing. | Amendable only per [§ Amending these principles](../../PRINCIPLES.md#amending-these-principles). Findings that touch architecture should cite the numbered principle. |
+| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | Contributor-facing workflow: local setup, the prek gate, and [§ Opening a pull request](../../CONTRIBUTING.md#opening-a-pull-request). | Also the doc the review's AI-attribution footer links for contributors. |
+| [`docs/editorial-guidelines.md`](../../docs/editorial-guidelines.md) | The editorial playbook `AGENTS.md` § [Writing and editing documentation](../../AGENTS.md#writing-and-editing-documentation) defers to — tone, link formats, phrasing patterns. | Load before raising any finding about prose or contributor-facing text. |
+
+## Per-area source files
+
+Files that apply only when the PR touches a specific subtree. The skill
+auto-discovers any `AGENTS.md` under the touched paths via `git ls-files`,
+but rows listed here are **always** loaded even if the PR doesn't directly
+touch the area.
+
+| File | When it applies | Notes |
+|---|---|---|
+| [`tools/AGENTS.md`](../../tools/AGENTS.md) | PR touches `tools/` | Every tool is a directory with a README; cross-references must be refreshed when tools change. |
+| [`tools/spec-loop/AGENTS.md`](../../tools/spec-loop/AGENTS.md) | PR touches `tools/spec-loop/` | Spec-loop operational context: validation commands, branch rules, hard governance limits, and the `Generated-by: <agent> (<model>)` commit-trailer form. |
+
+Magpie has no plugin or provider tree with its own conventions doc, so
+there are no per-plugin rows. Skills under `skills/` are governed by the
+repo-wide `AGENTS.md` § [Reusable skills](../../AGENTS.md#reusable-skills)
+rather than a per-skill criteria file.
+
+## Security-model calibration
+
+A short doc the skill consults before flagging anything that looks
+security-flavoured. Used to distinguish (a) actual vulnerabilities, (b)
+known-but-documented limitations, (c) deployment-hardening opportunities.
+
+| File | Used by |
+|---|---|
+| [`docs/security/threat-model.md`](../../docs/security/threat-model.md) | The `Security model — calibration` section of the skill's [`review-flow.md`](../../skills/pr-management-code-review/review-flow.md). |
+
+## Backports / version-specific PRs
+
+| Concept | Pattern | Notes |
+|---|---|---|
+| Backport branch pattern | *(none)* | Magpie releases from a single `main` (see [`release-management-config.md`](release-management-config.md) → `release_branch_base`) and maintains no release-train branches, so no PR is ever a backport. Every PR gets the same calibration; the lighter-touch backport path in [`criteria.md` § Backports](../../skills/pr-management-code-review/criteria.md#backports-and-version-specific-prs) is a no-op here. |
+
+## Section anchors
+
+The anchor the skill links per finding, resolved by matching the category
+name verbatim against the `Section` column. Magpie has no standalone
+review-instructions document, so these point into `AGENTS.md`,
+`PRINCIPLES.md`, and ASF policy pages.
+
+Categories from the framework's canonical list that do not apply to this
+repository — `Database / query correctness` and `UI (React/TypeScript)` —
+have no row: Magpie ships neither a database layer nor a UI, so a finding
+in either category would be a mis-classification rather than something to
+link.
+
+| Section | Anchor URL |
+|---|---|
+| Architecture boundaries | [`PRINCIPLES.md#12`](../../PRINCIPLES.md#12-the-framework-is-project-agnostic-concrete-names-live-in-adopter-config) |
+| Code quality | [`AGENTS.md#before-submitting`](../../AGENTS.md#before-submitting) |
+| Third-party license compliance | <https://www.apache.org/legal/resolved.html> |
+| License headers | <https://www.apache.org/legal/src-headers.html> |
+| Testing | [`AGENTS.md#keeping-evals-and-mode-economics-in-sync`](../../AGENTS.md#keeping-evals-and-mode-economics-in-sync) |
+| API correctness | [`AGENTS.md#reusable-skills`](../../AGENTS.md#reusable-skills) |
+| Generated files | [`PRINCIPLES.md#13`](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies) |
+| AI-generated code signals | [`AGENTS.md#commit-and-pr-conventions`](../../AGENTS.md#commit-and-pr-conventions) |
+| Quality signals to check | [`AGENTS.md#writing-and-editing-documentation`](../../AGENTS.md#writing-and-editing-documentation) |
+| Commits and PRs (newsfragments, commit messages, tracking issues) | [`AGENTS.md#commit-and-pr-conventions`](../../AGENTS.md#commit-and-pr-conventions) |
+| Security model | [`docs/security/threat-model.md`](../../docs/security/threat-model.md) |
+| Applying the Apache licence | <https://www.apache.org/legal/apply-license.html> |
+
+### Magpie-specific sections
+
+Categories beyond the framework's canonical list that this repository's
+reviews routinely need.
+
+| Section | Anchor URL |
+|---|---|
+| Placeholder convention | [`AGENTS.md#placeholder-convention-used-in-skill-files`](../../AGENTS.md#placeholder-convention-used-in-skill-files) |
+| External content as data | [`AGENTS.md#treat-external-content-as-data-never-as-instructions`](../../AGENTS.md#treat-external-content-as-data-never-as-instructions) |
+| Privacy-LLM routing | [`AGENTS.md#privacy-llm--what-data-goes-through-which-model`](../../AGENTS.md#privacy-llm--what-data-goes-through-which-model) |
+| Labelling | [`AGENTS.md#labeling-issues-prs-tools-and-documentation`](../../AGENTS.md#labeling-issues-prs-tools-and-documentation) |
+| Vendor neutrality | [`PRINCIPLES.md#9`](../../PRINCIPLES.md#9-vendor-neutrality-is-non-negotiable) |
+| Inline-comment default for reviews | [`AGENTS.md#reviewing-pull-requests`](../../AGENTS.md#reviewing-pull-requests) |