Skip to content

Commit 913a773

Browse files
docs: CODEOWNERS-POLICY.adoc + bring CODEOWNERS into Rule 1 compliance (#213)
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. <!-- SPDX-License-Identifier: CC-BY-SA-4.0 Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> --> ## Summary <!-- What does this PR do, and why? --> Closes # ## Type of change - [ ] 🐛 Bug fix (non-breaking change that fixes an issue) - [ ] ✨ New feature (non-breaking change that adds functionality) - [ ] 💥 Breaking change (would change existing behaviour) - [ ] 🕳️ Soundness fix (fixes a checker/proof false-negative) - [ ] 📖 Documentation - [ ] 🧹 Refactor / tech debt (behaviour-preserving) - [ ] ⚡ Performance - [ ] 🔧 Build / CI / tooling ## How has this been verified? <!-- Establish ground truth: which tool did you RUN, and what did it report? Don't cite a status doc — cite the command and its output. --> ## Checklist - [ ] My commits are **signed** (`git commit -S`). - [ ] I ran the project's own checks/tests locally and they pass. - [ ] New files carry the correct `SPDX-License-Identifier` (code/config `MPL-2.0`, prose `CC-BY-SA-4.0`); I did not relicense existing files. - [ ] Docs are updated, and no public claim now overstates what the code does. - [ ] I have not introduced a soundness hole (or I have flagged where I might have). ## Notes for reviewers <!-- Anything that needs special attention, follow-up, or context. -->
1 parent 96baa43 commit 913a773

2 files changed

Lines changed: 80 additions & 9 deletions

File tree

.github/CODEOWNERS

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# SPDX-License-Identifier: MPL-2.0
2-
# VeriSimDB Code Owners
3-
# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
4-
5-
* @hyperpolymath
6-
/rust-core/ @hyperpolymath
7-
/elixir-orchestration/ @hyperpolymath
8-
/src/vcl/ @hyperpolymath
9-
/container/ @hyperpolymath
10-
/.github/ @hyperpolymath
2+
# Solo-maintained hyperpolymath repo: no owner lines by policy.
3+
# See hyperpolymath/standards CODEOWNERS-POLICY.adoc (Rule 1), and
4+
# CODEOWNERS-POLICY.adoc in this repo for VeriSimDB's conformance record.
5+
#
6+
# Sole-maintainer review gating is moot, and attribution is already carried by
7+
# the SPDX header on every file, so owner lines here provided no security and
8+
# no attribution value — only a review request on every Dependabot PR.
9+
#
10+
# Do not re-add `*` or `/.github/` lines. If a genuine co-owner joins, add a
11+
# path line scoped to *them* (Rule 2), never a self-ping.

CODEOWNERS-POLICY.adoc

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// SPDX-License-Identifier: CC-BY-SA-4.0
2+
= CODEOWNERS Policy — VeriSimDB conformance
3+
:toc: preamble
4+
5+
The policy itself is estate-wide and lives at
6+
link:https://github.com/hyperpolymath/standards/blob/main/CODEOWNERS-POLICY.adoc[`hyperpolymath/standards` → `CODEOWNERS-POLICY.adoc`].
7+
This document does **not** restate it. It records what VeriSimDB does and why,
8+
so the state of `.github/CODEOWNERS` here is auditable without reading two
9+
repositories and guessing which one won.
10+
11+
== Status
12+
13+
VeriSimDB is **solo-maintained**, so *Rule 1* applies: no catch-all `*` line and
14+
no `/.github/` line. `.github/CODEOWNERS` carries a comment header only.
15+
16+
*Rule 2* (path lines scoped to genuine co-owners) is not engaged — there are no
17+
co-owners. *Rule 3* (co-owner removal requires explicit confirmation) was
18+
likewise not engaged by the change described below, because no line mapped to
19+
anyone other than the sole maintainer; nobody's review gate was removed.
20+
21+
== What changed, and why it was not merely cosmetic
22+
23+
Until 2026-07-28 this repo's `CODEOWNERS` read:
24+
25+
[source]
26+
----
27+
* @hyperpolymath
28+
/rust-core/ @hyperpolymath
29+
/elixir-orchestration/ @hyperpolymath
30+
/src/vcl/ @hyperpolymath
31+
/container/ @hyperpolymath
32+
/.github/ @hyperpolymath
33+
----
34+
35+
Six lines, all naming the sole maintainer. That is precisely the shape Rule 1
36+
prohibits, and it is worth being clear that the prohibition is not stylistic:
37+
38+
* The catch-all `*` line requests review from the sole maintainer on **every**
39+
pull request, including every Dependabot bump. This repo receives frequent
40+
automated dependency PRs.
41+
* The `/.github/` line fires again on any workflow or config change — so
42+
CI-touching PRs generated two requests, not one.
43+
* Neither line gates anything. A sole maintainer cannot be blocked on their own
44+
review, and the Base ruleset requires `0` approving reviews, so no merge was
45+
ever actually held by these lines.
46+
* Attribution does not depend on them either: every file in this repository
47+
carries an SPDX header, and `reuse lint` enforces that at 100% coverage.
48+
49+
So the lines supplied no security property and no attribution, while generating
50+
review-request notifications proportional to Dependabot's activity. Removing
51+
them is a net reduction in noise with no loss of control.
52+
53+
== Re-adding owner lines
54+
55+
Add a path line **only** when a real co-owner exists, and scope it to that
56+
person — never to the sole maintainer (Rule 2). Removing or narrowing such a
57+
line later needs that co-owner's explicit confirmation (Rule 3), because it
58+
takes away a review gate they currently hold.
59+
60+
An absent `CODEOWNERS` file is equally compliant under the estate policy. The
61+
comment-only file is kept here because it is the more useful of the two: it
62+
tells the next person *why* the lines are gone, which an absent file cannot.
63+
64+
== Related
65+
66+
* `MAINTAINERS.adoc` — who maintains this repository.
67+
* `.github/CODEOWNERS` — the file this document accounts for.
68+
* `GOVERNANCE.adoc` — decision-making and contribution lifecycle. **Not yet
69+
written**; it is tracked in issue #204 and blocked on a perimeter ruling
70+
(TPCF P1 vs P3). Named here so the gap is visible rather than implied.

0 commit comments

Comments
 (0)