apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-09 01:35:18 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
omnigraph/docs/codeowners.md
Andrew Altshuler 730712b73f
codeowners: yml source of truth + generator + drift CI (#88) 
* codeowners: generator + drift CI + initial roles

Source-of-truth approach to CODEOWNERS: yml is hand-edited, CODEOWNERS
is generated and CI-enforced. Every role change is a reviewable PR
with a permanent in-repo audit trail. No GitHub UI clicks, no shadow
state.

Initial roles:

  engineering  @aaltshuler            owns crates/** + default (.github/,
                                       scripts/, Cargo.*, openapi.json,
                                       everything else not docs)

  docs         @aaltshuler @ragnorc   owns docs/**, README.md, AGENTS.md,
                                       CLAUDE.md, SECURITY.md

Per GitHub semantics, multiple owners on a CODEOWNERS line means "any
one satisfies the review" — for docs, either named member can approve.
Strict "N distinct approvers" would need a CI workaround (not wired
today; tracked for future hardening).

Components:

- .github/codeowners-roles.yml — source of truth. Edit this.
- .github/scripts/render-codeowners.py — generator (PyYAML; ~100 LoC).
- .github/CODEOWNERS — generated. CI rejects hand-edits.
- .github/workflows/codeowners.yml — two checks:
  * drift: re-render and assert CODEOWNERS matches.
  * noedit: reject PRs that edit CODEOWNERS without editing the yml.
- docs/codeowners.md — explains the source-of-truth pattern, how to
  change roles, how to add new roles.
- AGENTS.md topic-index row.

What's NOT in this PR:

- Branch protection on main (separate PR; needs `gh api` call against
  the org).
- Required-reviewer enforcement (depends on branch protection landing).
- Required CI status checks (depends on branch protection landing).
- Scheduled rotation (the schedule: block in the yml + a weekly
  workflow). Today's roles are stable; rotation isn't needed yet.
- Linear-as-source-of-truth integration (Approach 4 from the design
  discussion; deferred).

Verified:
- Generator output is deterministic (idempotent re-runs).
- scripts/check-agents-md.sh OK (28 links, 28 docs).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* codeowners: fix catch-all ordering (Devin review #88)

Devin caught a real bug: GitHub CODEOWNERS uses "last match wins"
semantics, but the generator emitted the catch-all `*` AFTER specific
patterns. Net effect: `*` won for every file, silently nullifying the
docs role and never routing reviews to @ragnorc.

Fix is one-line — emit the default `*` line before iterating the
specific paths. Also:

- Added a regression assertion in the generator: after rendering, the
  first non-comment line must start with `*` if a default is
  configured. Generator exits non-zero otherwise. Catches the same
  class of mistake in any future refactor.
- Rewrote the yml header comment, which incorrectly stated "keep
  more-specific paths after broader patterns" (correct for GitHub
  semantics but the generator was doing the opposite — so the comment
  read as a description of behavior when it was actually a contradicted
  intention).

Verified by re-rendering: `*` is now line 12, `crates/**` is line 14,
`docs/**` is line 15, etc. README.md matches both `*` and `README.md`;
`README.md` is later → wins → @aaltshuler + @ragnorc both assigned.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 17:26:06 +03:00

2.1 KiB
Raw Blame History

Code ownership

.github/CODEOWNERS is generated — not hand-edited. The source of truth is .github/codeowners-roles.yml, expanded by .github/scripts/render-codeowners.py. CI rejects drift between the two and rejects direct edits to CODEOWNERS that don't accompany a yml change.

This setup gives every role change a reviewable PR and a permanent in-repo audit trail (git log .github/codeowners-roles.yml).

Current roles

Role Members Scope
engineering @aaltshuler All code under crates/**, repo infrastructure, default for unmapped paths
docs @aaltshuler, @ragnorc docs/**, README.md, AGENTS.md, CLAUDE.md, SECURITY.md

GitHub treats multiple owners in a CODEOWNERS line as "any one of them satisfies the review requirement". For docs, either named member can approve. To require N distinct approvers on a specific path, layer a CI check on top (not currently configured).

How to change role membership or path mappings

  1. Edit .github/codeowners-roles.yml.
  2. Run python3 .github/scripts/render-codeowners.py (requires PyYAML; pip install pyyaml).
  3. Commit both files in the same PR.

CI fails the PR if:

  • CODEOWNERS was edited without a corresponding yml change, or
  • The yml was changed but the rendered CODEOWNERS doesn't match.

How to add a new role

  1. Add a new entry to roles: in the yml with a description and members list.
  2. Reference the role from paths: (or default:).
  3. Regenerate + commit as above.

Why a generator, not direct CODEOWNERS edits?

  • Audit trail: git log .github/codeowners-roles.yml is the canonical record of every role change. The rendered CODEOWNERS is a derived artifact.
  • Roles are first-class: paths reference roles, not raw handles. Renaming a person or rotating a role updates one place, not every path.
  • Future extension: scheduled rotation (weekly on-call, quarterly leads) plugs into the same yml without changing the path mappings. Not enabled today.
  • Consistency with the product: omnigraph itself enforces auditable Cedar policy. The repo's code-owner policy follows the same "policy as reviewed code" pattern.