From 98866863cd9079173200ac6c01f2657c6d92bdfb Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 29 Jul 2026 08:39:01 +0100 Subject: [PATCH] docs: CODEOWNERS-POLICY.adoc + bring CODEOWNERS into Rule 1 compliance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two of the eight files #204 tracks, landed together because writing the policy document while violating the policy would have been self-contradictory. `.github/CODEOWNERS` carried six lines, every one naming the sole maintainer: * @hyperpolymath /rust-core/ @hyperpolymath /elixir-orchestration/ @hyperpolymath /src/vcl/ @hyperpolymath /container/ @hyperpolymath /.github/ @hyperpolymath The catch-all `*` and the `/.github/` line are precisely the two shapes `hyperpolymath/standards` CODEOWNERS-POLICY.adoc Rule 1 prohibits for solo-maintained repos, and the prohibition is not stylistic: * `*` requested a review from the sole maintainer on **every** PR, including every Dependabot bump — and this repo gets a lot of those. * `/.github/` fired again on workflow changes, so CI-touching PRs generated two requests rather than one. * Neither gated anything. A sole maintainer cannot be blocked on their own review, and the Base ruleset requires 0 approving reviews, so no merge was ever actually held by these lines. * Attribution never depended on them: every file carries an SPDX header and `reuse lint` enforces that at 100%. Replaced with the canonical comment-only header. Rule 3 (co-owner removal needs explicit confirmation) is **not** engaged — no line mapped to anyone other than the sole maintainer, so nobody's review gate was removed. Worth stating explicitly, since "deleting CODEOWNERS lines" is otherwise exactly the shape of change Rule 3 exists to prevent. `CODEOWNERS-POLICY.adoc` deliberately **references** the estate policy rather than forking it — a second copy would drift, and then the repo would have two policies disagreeing. What it adds is the conformance record: what this repo does, which rules are engaged, and why the removed lines were noise rather than control. That is the part that cannot live upstream. The doc names `GOVERNANCE.adoc` as not-yet-written and blocked on the TPCF perimeter ruling, rather than linking to it as though it exists. The gap is visible instead of implied. Verified: `tests/doc-consonance-gate.sh` passes (no "VeriSim Query Language" misnomer); `reuse lint` compliant — `REUSE.toml` already globs `**/*.adoc` to CC-BY-SA-4.0, so the new file needed no annotation change. --- .github/CODEOWNERS | 19 ++++++------ CODEOWNERS-POLICY.adoc | 70 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 9 deletions(-) create mode 100644 CODEOWNERS-POLICY.adoc diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 890c0e0..ecb16aa 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,10 +1,11 @@ # SPDX-License-Identifier: MPL-2.0 -# VeriSimDB Code Owners -# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners - -* @hyperpolymath -/rust-core/ @hyperpolymath -/elixir-orchestration/ @hyperpolymath -/src/vcl/ @hyperpolymath -/container/ @hyperpolymath -/.github/ @hyperpolymath +# Solo-maintained hyperpolymath repo: no owner lines by policy. +# See hyperpolymath/standards CODEOWNERS-POLICY.adoc (Rule 1), and +# CODEOWNERS-POLICY.adoc in this repo for VeriSimDB's conformance record. +# +# Sole-maintainer review gating is moot, and attribution is already carried by +# the SPDX header on every file, so owner lines here provided no security and +# no attribution value — only a review request on every Dependabot PR. +# +# Do not re-add `*` or `/.github/` lines. If a genuine co-owner joins, add a +# path line scoped to *them* (Rule 2), never a self-ping. diff --git a/CODEOWNERS-POLICY.adoc b/CODEOWNERS-POLICY.adoc new file mode 100644 index 0000000..41095e5 --- /dev/null +++ b/CODEOWNERS-POLICY.adoc @@ -0,0 +1,70 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += CODEOWNERS Policy — VeriSimDB conformance +:toc: preamble + +The policy itself is estate-wide and lives at +link:https://github.com/hyperpolymath/standards/blob/main/CODEOWNERS-POLICY.adoc[`hyperpolymath/standards` → `CODEOWNERS-POLICY.adoc`]. +This document does **not** restate it. It records what VeriSimDB does and why, +so the state of `.github/CODEOWNERS` here is auditable without reading two +repositories and guessing which one won. + +== Status + +VeriSimDB is **solo-maintained**, so *Rule 1* applies: no catch-all `*` line and +no `/.github/` line. `.github/CODEOWNERS` carries a comment header only. + +*Rule 2* (path lines scoped to genuine co-owners) is not engaged — there are no +co-owners. *Rule 3* (co-owner removal requires explicit confirmation) was +likewise not engaged by the change described below, because no line mapped to +anyone other than the sole maintainer; nobody's review gate was removed. + +== What changed, and why it was not merely cosmetic + +Until 2026-07-28 this repo's `CODEOWNERS` read: + +[source] +---- +* @hyperpolymath +/rust-core/ @hyperpolymath +/elixir-orchestration/ @hyperpolymath +/src/vcl/ @hyperpolymath +/container/ @hyperpolymath +/.github/ @hyperpolymath +---- + +Six lines, all naming the sole maintainer. That is precisely the shape Rule 1 +prohibits, and it is worth being clear that the prohibition is not stylistic: + +* The catch-all `*` line requests review from the sole maintainer on **every** + pull request, including every Dependabot bump. This repo receives frequent + automated dependency PRs. +* The `/.github/` line fires again on any workflow or config change — so + CI-touching PRs generated two requests, not one. +* Neither line gates anything. A sole maintainer cannot be blocked on their own + review, and the Base ruleset requires `0` approving reviews, so no merge was + ever actually held by these lines. +* Attribution does not depend on them either: every file in this repository + carries an SPDX header, and `reuse lint` enforces that at 100% coverage. + +So the lines supplied no security property and no attribution, while generating +review-request notifications proportional to Dependabot's activity. Removing +them is a net reduction in noise with no loss of control. + +== Re-adding owner lines + +Add a path line **only** when a real co-owner exists, and scope it to that +person — never to the sole maintainer (Rule 2). Removing or narrowing such a +line later needs that co-owner's explicit confirmation (Rule 3), because it +takes away a review gate they currently hold. + +An absent `CODEOWNERS` file is equally compliant under the estate policy. The +comment-only file is kept here because it is the more useful of the two: it +tells the next person *why* the lines are gone, which an absent file cannot. + +== Related + +* `MAINTAINERS.adoc` — who maintains this repository. +* `.github/CODEOWNERS` — the file this document accounts for. +* `GOVERNANCE.adoc` — decision-making and contribution lifecycle. **Not yet + written**; it is tracked in issue #204 and blocked on a perimeter ruling + (TPCF P1 vs P3). Named here so the gap is visible rather than implied.