docs(principles): add operational principles document#147
Conversation
andreahlert
requested review from
RussellSpitzer,
amoghrajesh,
andrewmusselman,
eladkal,
gopidesupavan,
jbonofre,
justinmclean,
paulk-asert,
ppkarwasz,
rusackas and
zeroshade
…intainer-authored (justinmclean)
…rinciple interpretation rule (justinmclean)
A skill is always a directory with SKILL.md as entrypoint, even for one-file workflows. SKILL.md stays under 500 lines; longer reference material moves into sibling markdown linked one level deep. Matches the runtime contract documented at https://code.claude.com/docs/en/skills and https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices, and reflects how skills in this repo (contributor-nomination, pr-management-code-review, pr-management-mentor) are already authored.
…auto-merge gap (justinmclean)
…te as last resort (justinmclean)
|
There still a couple of ASF policy issues:
The rest looks good to me. Running this over our existing skills gave me this. Do we want to revisit the P14 size limit? Audit: existing skills vs PRINCIPLES.md (PR #147)Date: 2026-05-29 Two principles are the real gates: P14 (size + structure) and P3 + P12 (non-ASF first-class + placeholder hygiene). P0, P6, P8, and P14's sibling-link rule are largely already satisfied. P14 size violations (the ≤500-line rule)13 of 30 SKILL.md files are over. Ranked worst first, with how much they overshoot:
Pattern: every
The sibling-depth rule is clean everywhere: nothing is nested more than one level, and every existing sibling is linked from SKILL.md. P3 + P12: non-ASF adopters and placeholder hygieneThis is the substantive gap, and it is bigger than the size cliff. The entire security-issue-* family is implicitly ASF-only.
Either is fine. Pretending the current state is project-agnostic is not.
What's already fine
|
|
Super cool analysis @justinmclean ! Love it.. Indeed some of the details of some of the SKILS are still not generic (Security) .. I am running the last tests in Airflow and will make the generic change soon. |
|
And of course... we will make them smaller / split :) |
|
first from 5 PRs to make security workflow generic: #381 |
|
Audit: how well does I ran the current
Actionable gaps (each verified directly):
Notes: P11's signing/reproducibility items are expected pre-first-release, not regressions. (Tooling-assisted audit; the PARTIAL/HOLD calls are evidence-backed but not exhaustively proven.) |
|
Generic property achieved :) |
Addresses review feedback that 'bytes are identical' is too strong for a project-agnostic framework. Toolchains vary in their ability to produce byte-identical output; some have known divergence sources (timestamps, file ordering, path embedding). P11 now requires byte-identical builds where achievable, and where the toolchain makes that impractical, the release process must document the divergence and provide an alternative local verification mechanism. The 'no code without reviewed PR' guard stays absolute. Refs: PR apache#147 review
The doctoc-generated TOC was placed above the Apache license header, which breaks tooling that expects the license notice in the first few lines of the file. Move the license block to line 1, followed by the TOC. Refs: PR apache#147 review
… policy Three fixes from PR apache#147 review by @justinmclean: 1. Amendment vote model: 'release vote' -> 'code-modification vote' The encoded rule (>=3 binding +1, any binding -1 vetoes) matches ASF consensus approval for code modifications, not majority approval for releases. 2. Veto-justification requirement: A binding -1 must now include a technical justification. Without one the veto is invalid and has no weight, matching ASF voting policy. 3. Generative tooling disclosure: P17 now requires a 'Generated-by: <tool>' token in commit messages for AI-authored contributions, per ASF Generative Tooling Guidance.
@justinmclean thanks for the detailed policy review. All three issues fixed in the latest push:
Let me know if anything still looks off. |
|
@potiuk thanks for the thorough audit. A few updates since you ran this: P3 + P12 (HOLD, not gap): The security genericization series is complete — #381 through #399 (PR1-PR5) are all merged. The ASF-coupled assumptions are now config-driven placeholders. setup-steward's self-references to apache/airflow-steward are legitimate per P12's carve-out for the framework's own repo. P14 (still GAP, but shrinking): #410 already landed and slimmed security-issue-sync from 3425 to 658 lines. The remaining overshoots are queued for split. Validator line-count check comes in a follow-up PR once the bulk of splits land. P0 / P8 / P1-P16: Agree on all counts. P0 (injection-guard blind spot) and P8 (missing evals) are quick wins I'll pick up next. P1/P16 audit logging is the bigger pre-release item — tied to RFC-AI-0004 implementation, not this PR. Does the updated P3/P12 state look right to you? |
|
I will merge it now - so that we can do rename.. But we should definitely work on it. |
7 participants
Summary
Adds
PRINCIPLES.mdat the repo root. Proposed, not landed-as-final. The whole point of the PR is to bike-shed the principles themselves before they bind anyone.Motivation
RFC-AI-0004 sets the six baseline principles every adopter signs. It is deliberately minimal because it has to travel: anything more specific would make the contract harder for non-Steward projects to take on.
The framework itself needs a tighter ruler. Skills are the unit of authorship here, and skills are subjective by construction. The same skill catalogue will end up touching PR triage, security-report handling, release artefacts, mailing-list drafts, contributor mentoring. Those surfaces have very different blast radius, and very different trust requirements.
When one markdown file can reach that many places, "the RFC permits it" is too coarse a check at PR-review time. Reviewers need something finer they can point at: which commitments block a release, what evidence promotes a mode, when telemetry is allowed at all, what an auditable agent action looks like.
This document is that ruler. It restates the six baseline principles in their operational shape, and adds the project-internal commitments the RFC leaves out on purpose: eval as a release blocker, contributor-sentiment gating on mode promotion, no default telemetry, reproducible releases from signed source, maintainer education shipped alongside the code.
What's inside
19 ordered principles. Earlier ones outrank later ones when they collide. A PR or skill that violates a principle is wrong even if every test passes, and any committer can block on principle grounds until the change complies, or until an amendment carries through governance.
The doc header positions this explicitly as built on top of RFC-AI-0004, not as a competing RFC.
Happy to drop, fold, or rewrite anything based on the thread.