Skip to content

Commit 0b68f3c

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
docs(policy): add canonical CODEOWNERS policy (standards#55) (#58)
## Summary Resolves the policy decision in #55 by codifying a **canonical CODEOWNERS standard** for all `hyperpolymath/*` repos (modelled on the existing `LICENCE-POLICY.adoc`). - **`CODEOWNERS-POLICY.adoc`** (new, root) — three rules: - Rule 1: solo-owned repos carry **no** catch-all `*` or `/.github/workflows/` lines (this is what was flooding `reason:review_requested` from Dependabot). - Rule 2: path lines kept only for genuine co-owners. - Rule 3: removing/narrowing a co-owner's gate needs explicit confirmation. - Includes the full #55 per-repo **decision matrix** for the 15 remaining `github-actions`-ecosystem repos, plus rollout tracking for the 18 already-opened `*`-line PRs. - **`idaptik`** is resolved as the *only* Rule 2/3 case: `@JoshuaJewell` is a real co-owner, so its workflow gate is retained (narrowed to `@JoshuaJewell`, self-ping of `@hyperpolymath` dropped) — flagged as requiring co-owner confirmation per Rule 3. - Canonical `CODEOWNERS.template` added to the RSR templates dir. - README Overview wired to the new policy; ADR-001 recorded in `.machine_readable/6a2/META.a2ml`. Note: per-repo `CODEOWNERS` edits land in each target repo (out of scope for this repo). This standards repo has no `CODEOWNERS` lines of its own and is already compliant; this PR is the canonical reference those edits cite. ## Test plan - [ ] `CODEOWNERS-POLICY.adoc` renders and all internal/external links resolve (Lychee) - [ ] SPDX headers present on both new files (passes hypatia-scan) - [ ] `META.a2ml` ADR entry parses - [ ] Confirm `idaptik` Rule 3 disposition with `@JoshuaJewell` before executing that per-repo edit https://claude.ai/code/session_01GTo7dz32ZgxuHXefv8BGqn --- _Generated by [Claude Code](https://claude.ai/code/session_01GTo7dz32ZgxuHXefv8BGqn)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 8075005 commit 0b68f3c

4 files changed

Lines changed: 163 additions & 2 deletions

File tree

‎.machine_readable/6a2/META.a2ml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@
44
# META.a2ml — Standards meta-level information
55
[metadata]
66
version = "1.0.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-05-15"
88

99
[project-info]
1010
license = "PMPL-1.0-or-later"
1111
author = "Jonathan D.A. Jewell (hyperpolymath)"
1212

1313
[architecture-decisions]
1414
decisions = [
15-
# No ADRs recorded
15+
{ id = "ADR-001", date = "2026-05-15", title = "CODEOWNERS policy for hyperpolymath repos", status = "accepted", ref = "CODEOWNERS-POLICY.adoc", issue = "standards#55", summary = "Solo-owned repos carry no catch-all `*` or `/.github/workflows/` CODEOWNERS lines (silences Dependabot review_requested flood); path lines kept only for genuine co-owners; co-owner removal needs explicit confirmation." }
1616
]
1717

1818
[development-practices]

‎CODEOWNERS-POLICY.adoc‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= Hyperpolymath CODEOWNERS Policy
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
:revnumber: 1.0.0
6+
:revdate: 2026-05-15
7+
:toc:
8+
:toc-placement: preamble
9+
10+
Canonical `CODEOWNERS` policy for all `hyperpolymath/*` repositories.
11+
All maintainers and AI agents must follow this document. It resolves
12+
link:https://github.com/hyperpolymath/standards/issues/55[standards#55].
13+
14+
== Problem
15+
16+
GitHub auto-requests review from every matching `CODEOWNERS` entry on
17+
*every* pull request — including Dependabot PRs. On solo-owned repos the
18+
only matching owner is the sole maintainer, so every dependency bump
19+
fires a `reason:review_requested` notification that conveys no
20+
information (the sole maintainer is going to review their own repo
21+
anyway). Across ~18 active `hyperpolymath/*` repos this produced a
22+
recurring notification flood.
23+
24+
Two `CODEOWNERS` line shapes cause this:
25+
26+
* the catch-all `* @owner` line — triggered by *all* Dependabot
27+
ecosystems (cargo, mix, nix, npm, …);
28+
* the `/.github/workflows/` path line — triggered specifically by the
29+
Dependabot `github-actions` ecosystem, which bumps action versions by
30+
editing workflow files.
31+
32+
== The Standard
33+
34+
=== Rule 1 — Solo-owned repos carry no functional CODEOWNERS lines
35+
36+
For a repository whose only code owner would be the sole maintainer,
37+
`CODEOWNERS` MUST NOT contain a catch-all (`*`) line *or* a
38+
`/.github/workflows/` (or `.github/workflows/`) line.
39+
40+
Such a repo SHOULD either omit `CODEOWNERS` entirely or keep only a
41+
comment header (SPDX + a one-line note). Sole-maintainer review gating is
42+
moot, and attribution is already carried by the SPDX header on every
43+
file, so the lines provide neither security nor attribution value — only
44+
noise.
45+
46+
=== Rule 2 — Path lines are kept only for real co-owners
47+
48+
A path-specific `CODEOWNERS` line is justified *only* when it maps to a
49+
collaborator other than the sole maintainer who genuinely should be
50+
auto-pinged for changes under that path. When such a co-owner exists,
51+
keep the path line but scope it to the co-owner and drop any redundant
52+
self-ping of the sole maintainer.
53+
54+
=== Rule 3 — Co-owner removal requires explicit confirmation
55+
56+
Dropping or narrowing a path line that currently auto-requests review
57+
from a co-owner removes that co-owner's review gate. This MUST NOT be
58+
done without the co-owner's (or repo lead's) explicit confirmation.
59+
60+
== Canonical Templates
61+
62+
=== Solo-owned repo (`CODEOWNERS`)
63+
64+
[source]
65+
----
66+
# SPDX-License-Identifier: PMPL-1.0-or-later
67+
# Solo-maintained hyperpolymath repo: no owner lines by policy.
68+
# See hyperpolymath/standards CODEOWNERS-POLICY.adoc (Rule 1).
69+
# Sole-maintainer review is moot; SPDX headers carry attribution.
70+
----
71+
72+
(An absent `CODEOWNERS` file is equally compliant.)
73+
74+
=== Multi-owner repo (`CODEOWNERS`)
75+
76+
[source]
77+
----
78+
# SPDX-License-Identifier: PMPL-1.0-or-later
79+
# Path lines map ONLY to genuine co-owners (Rule 2).
80+
# Do not add a catch-all `*` line.
81+
/.github/workflows/ @co-owner-handle
82+
----
83+
84+
== Decision Matrix — standards#55 remaining repos
85+
86+
The 2026-05-14 batch already opened 18 PRs dropping the catch-all
87+
`* @hyperpolymath` line (cargo/mix/nix/npm noise). This matrix resolves
88+
the remaining `github-actions`-ecosystem `.github/workflows/` line.
89+
90+
[cols="2,1,3", options="header"]
91+
|===
92+
| Repo | Resolution | Basis
93+
94+
| gitbot-fleet | Drop line | Solo-owned (Rule 1)
95+
| hypatia | Drop line | Solo-owned (Rule 1)
96+
| boj-server | Drop line | Solo-owned (Rule 1)
97+
| bofig | Drop line | Solo-owned (Rule 1)
98+
| idaptik | Keep, scope to `@JoshuaJewell` | Co-owned (Rule 2); self-ping of `@hyperpolymath` dropped, `@JoshuaJewell` gate retained per Rule 3
99+
| proof-of-work | Drop line | Solo-owned (Rule 1)
100+
| InvestigativeJournalist.jl | Drop line | Solo-owned (Rule 1)
101+
| TradeUnionist.jl | Drop line | Solo-owned (Rule 1)
102+
| echidna | Drop line | Solo-owned (Rule 1)
103+
| coq-jr | Drop line | Solo-owned (Rule 1)
104+
| cloudguard-server | Drop line | Solo-owned (Rule 1)
105+
| cloudguard-cli | Drop line | Solo-owned (Rule 1)
106+
| snifs | Drop line | Solo-owned (Rule 1)
107+
| somethings-fishy | Drop line | Solo-owned (Rule 1)
108+
| affinescript-vite | Drop line | Solo-owned (Rule 1)
109+
|===
110+
111+
idaptik is the sole Rule 3 case: `@JoshuaJewell` is a genuine co-owner,
112+
so its `.github/workflows/` gate is retained (narrowed to
113+
`@JoshuaJewell` only). All other 14 are solo-owned and take the Rule 1
114+
drop.
115+
116+
=== Rollout tracking
117+
118+
Per-repo `CODEOWNERS` edits land in each target repository, not in this
119+
standards repo (which has no `CODEOWNERS` lines of its own and is already
120+
compliant). This document is the canonical reference those PRs cite.
121+
122+
[cols="3,2", options="header"]
123+
|===
124+
| Batch | Status
125+
126+
| 18 PRs dropping catch-all `*` line (cargo/mix/nix/npm) | Opened 2026-05-14 (see standards#55 body)
127+
| 14 solo-owned repos dropping `.github/workflows/` line | Authorised by Rule 1 — execute per-repo
128+
| idaptik — narrow `.github/workflows/` to `@JoshuaJewell` | Authorised by Rule 2/3 — execute on co-owner confirmation
129+
|===
130+
131+
== Enforcement
132+
133+
* New repos: the RSR repo template ships no catch-all `CODEOWNERS` line;
134+
a `CODEOWNERS` file, if present, follows the canonical templates above.
135+
* Audit: a repo is non-compliant if `CODEOWNERS` contains a `*` line, or
136+
a `/.github/workflows/` line whose owners are limited to the sole
137+
maintainer. Grep check:
138+
+
139+
[source,bash]
140+
----
141+
grep -nE '^\s*\*\s|^\s*/?\.github/workflows/' CODEOWNERS 2>/dev/null
142+
----
143+
+
144+
Any catch-all match is a violation; a workflow-path match is a violation
145+
unless every listed owner is a genuine co-owner (Rule 2).
146+
147+
== See Also
148+
149+
* link:https://github.com/hyperpolymath/standards/issues/55[standards#55] — originating decision
150+
* `LICENCE-POLICY.adoc` (this directory) — companion canonical policy; SPDX headers cover attribution
151+
* `MAINTAINERS.adoc` (this directory) — maintainer-of-record (separate from CODEOWNERS auto-ping)
152+
* link:https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners[GitHub: About code owners]

‎README.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ This repository serves as the canonical source for policies, templates, and spec
2323
* **Session Management Standards** -- link:session-management-standards/README.adoc[canonical continuity, verify, and handover protocols]
2424
* **Contractiles / K9** -- link:contractiles/CANONICAL-TEMPLATES.adoc[canonical Must/Trust/Dust/Intent semantics] and Kennel/Yard/Hunt guidance
2525
* **Governance Templates** -- Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents
26+
* **CODEOWNERS Policy** -- link:CODEOWNERS-POLICY.adoc[canonical `CODEOWNERS` rules] (no catch-all/workflow lines on solo-owned repos)
2627
* **Licensing Framework** -- PMPL-1.0-or-later with Palimpsest philosophical principles
2728
* **Enforcement** -- CI/CD workflows and pre-commit hooks
2829

‎rhodium-standard-repositories/templates/CODEOWNERS.template‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Solo-maintained hyperpolymath repo: no owner lines by policy.
3+
# See hyperpolymath/standards CODEOWNERS-POLICY.adoc (Rule 1).
4+
# Sole-maintainer review is moot; SPDX headers carry attribution.
5+
#
6+
# Multi-owner repos only: add path lines scoped to genuine co-owners
7+
# (Rule 2), e.g. `/.github/workflows/ @co-owner-handle`.
8+
# Never add a catch-all `*` line.

0 commit comments

Comments
 (0)