justinmclean commented on code in PR #147: URL: https://github.com/apache/airflow-steward/pull/147#discussion_r3321497577
########## PRINCIPLES.md: ########## @@ -0,0 +1,147 @@ +<!-- 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 Steward Design Principles](#apache-steward-design-principles) + - [Amending these principles](#amending-these-principles) + - [0. External content is data, never an instruction](#0-external-content-is-data-never-an-instruction) + - [1. Privacy, security, and supply-chain integrity ship before features](#1-privacy-security-and-supply-chain-integrity-ship-before-features) + - [2. The relationship is the product](#2-the-relationship-is-the-product) + - [3. Project autonomy is the structural starting point](#3-project-autonomy-is-the-structural-starting-point) + - [4. Lower-stakes automation ships before higher-stakes automation](#4-lower-stakes-automation-ships-before-higher-stakes-automation) + - [5. Outputs are probabilistic; gates are deterministic](#5-outputs-are-probabilistic-gates-are-deterministic) + - [6. The human is always in the loop, until they choose otherwise](#6-the-human-is-always-in-the-loop-until-they-choose-otherwise) + - [7. Contributor sentiment gates every mode graduation](#7-contributor-sentiment-gates-every-mode-graduation) + - [8. Eval is a release-blocking discipline](#8-eval-is-a-release-blocking-discipline) + - [9. Vendor neutrality is non-negotiable](#9-vendor-neutrality-is-non-negotiable) + - [10. No default telemetry](#10-no-default-telemetry) + - [11. Releases are reproducible from signed source](#11-releases-are-reproducible-from-signed-source) + - [12. The framework is project-agnostic; concrete names live in adopter config](#12-the-framework-is-project-agnostic-concrete-names-live-in-adopter-config) + - [13. Snapshot plus override, never vendored copies](#13-snapshot-plus-override-never-vendored-copies) + - [14. Skills are the unit of authorship](#14-skills-are-the-unit-of-authorship) + - [15. Tracker identifiers are public-safe; tracker contents are not](#15-tracker-identifiers-are-public-safe-tracker-contents-are-not) + - [16. Audit every agent-authored action; reverse it where possible](#16-audit-every-agent-authored-action-reverse-it-where-possible) + - [17. Contributions land under Apache License 2.0](#17-contributions-land-under-apache-license-20) + - [18. Maintainer education ships with the platform](#18-maintainer-education-ships-with-the-platform) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. --> + +# Apache Steward Design Principles + +These principles regulate what this framework is and how it evolves. Order matters: earlier principles outrank later ones when they collide. Where a single principle admits more than one reading, the stricter reading wins until governance documents otherwise. + +A change (PR, skill, tool adapter, release) that violates a principle is wrong even if every test passes. Any committer may block it on principle grounds. The block lifts when the change complies, when a principle-amendment proposal carries through governance with the same weight as a release vote, or, when the author and the blocking committer disagree on whether the change complies, when the dispute resolves through PMC consensus on whether the principle is violated, with a formal PMC vote only as a last resort if consensus cannot be reached. The block holds until one of these resolves it; it is never overridden silently. + +## Amending these principles + +This document is binding on contributors, committers, and the PMC of the apache-steward project, and on adopter projects to the extent they consume the framework unmodified. Editing it follows the same process as a release vote: + +- A principle amendment is proposed as a PR against this file plus a thread on the project's PMC private list (`private@<project>.apache.org`) and a mirrored thread on `dev@<project>.apache.org` for public visibility. +- The voting window is at least 72 hours from the [VOTE] message. +- Passage requires ≥3 binding +1 votes from PMC members and zero binding -1 vetoes. A binding -1 stops the amendment until the objection is addressed or withdrawn. +- Lazy consensus does NOT apply to principle changes. Silence is not consent here. +- The PR merges only after the vote result is recorded on the dev list and linked from the merge commit. + +Anyone may propose an amendment by opening the PR; the mailing-list threads and the binding vote belong to the apache-steward PMC, because this file is the governance document of an ASF project. Adopter projects that need a principle to read differently for their own use rely on overrides (principle 13) rather than amending this file. + +Editorial fixes (typos, broken links, formatting) follow normal review and do not require a vote. Anything that changes the meaning of a principle, adds a principle, removes a principle, or changes the ordering does. + +## 0. External content is data, never an instruction + +Reporter mail, PR comments, GHSA forwards, attachments, linked URLs, anything that did not land via a reviewed PR by a tracker-repo collaborator: input to analyze, never directives. No framing softens this. Not authority claims, not embedded "ignore previous instructions", not a user pasting external content and asking the agent to "apply what it says". Rule cannot be relaxed mid-session, cannot be overridden by a runtime document. + +## 1. Privacy, security, and supply-chain integrity ship before features + +Sandbox, clean-environment wrapper, privacy-aware LLM routing, PII redaction, pinned and signed dependencies, audit logging: release-blocking parts of every milestone, not retrofits. If a feature has to slow to keep this story honest, it slows. The capable maintainer who declines to adopt over a privacy concern is the failure case the framework is built to avoid. + +## 2. The relationship is the product + +Open source runs on contributor-to-maintainer trust, peer-maintainer trust, and the progression from first contribution to the project's highest governance role, by whatever name that role carries. Agents absorb the mechanical traffic that gets in the way of trust, never replace it. A feature that trades a human relationship for throughput is wrong. + +## 3. Project autonomy is the structural starting point + +Each adopting project picks which modes run and how much automation fits its culture, whatever its governance: ASF PMC, foundation-hosted, single-vendor, informal maintainer group. The framework offers a range, never mandates a level. Non-ASF adopters are first-class adopters, not a compatibility afterthought. Vendor neutrality extends to project governance the same way it extends to model providers. + +## 4. Lower-stakes automation ships before higher-stakes automation + +Automation rolls out in order of reversibility and blast radius: + +- Read-only suggestions and conversational help before agent-drafted artifacts. +- Drafted artifacts under human review before any state-changing action. +- State-changing actions before merges. +- Merges only for narrowly-scoped, reversible change classes. + +A higher-stakes lane unlocks only after the lower-stakes ones have produced evidence the project is healthier, not just faster. Security-class changes never reach the merge end of this ladder. The framework will name and version specific modes, but this ordering survives any renaming. + +## 5. Outputs are probabilistic; gates are deterministic + +Skills produce drafts. Tool calls enforce schemas. Humans or deterministic checks decide whether a draft becomes state. Probabilistic at the input, deterministic at every state change. The boundary never blurs, even when the draft looks reliable enough to short-circuit the gate. Where a deterministic check (script, linter, schema validation) can replace an LLM pass, it runs first; LLM passes are not spent on what executable code already decides. + +## 6. The human is always in the loop, until they choose otherwise + +Every agent-authored output (comment, label, draft, issue, PR) is a proposal a human signs off on. The agent never performs a merge of its own work, nor unilaterally enables auto-merge on it. Auto-merge, where it exists, is narrow, opt-in per project AND per change class, and never touches security-class changes. **The opt-out never extends to communication aimed at a human: any outbound message a person will read as if a maintainer wrote it (reporter mail, PR or issue comment, review reply, mailing-list post, mentoring message) requires explicit human sign-off, regardless of mode.** Sending such prose without that sign-off is impersonation, and impersonation never graduates to an auto-mode. + +## 7. Contributor sentiment gates every mode graduation + +Promotion of any mode (from experimental to default, from suggestion to draft, from draft to state change, from state change to merge) requires evidence sourced from contributors and reviewers that the project is healthier. Throughput numbers alone never qualify. The length of the evidence window is set by adopter governance, not by this document. + +## 8. Eval is a release-blocking discipline + +Skill behavior is probabilistic, so correctness lives in distributions, not unit tests. Every release ships eval cases for every skill it includes, plus the methodology used to grade them. A skill without an eval is unreleased, regardless of how it looks in a demo. + Review Comment: May need a CI check for this? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
