From fa61bfe67874a140022408a2a556d5062969a9dd Mon Sep 17 00:00:00 2001 From: Dan Gil Date: Sun, 12 Jul 2026 16:02:59 -0500 Subject: [PATCH 1/3] docs: aic-codeowners skill + contributor guidance for generated CODEOWNERS Companion to the CODEOWNERS-as-code PR: an .agents/skills/aic-codeowners skill covering the four flows (who reviews a change, fixing a failing codeowners check, changing routing, external contributor grants), plus CONTRIBUTING.md and AGENTS.md pointers so contributors and agents find the playbook when the gate fires. Signed-off-by: Dan Gil --- .agents/skills/aic-codeowners/SKILL.md | 67 ++++++++++++++++++++++++++ AGENTS.md | 9 ++++ CONTRIBUTING.md | 9 ++++ 3 files changed, 85 insertions(+) create mode 100644 .agents/skills/aic-codeowners/SKILL.md diff --git a/.agents/skills/aic-codeowners/SKILL.md b/.agents/skills/aic-codeowners/SKILL.md new file mode 100644 index 000000000..30d1ebc15 --- /dev/null +++ b/.agents/skills/aic-codeowners/SKILL.md @@ -0,0 +1,67 @@ +--- +name: aic-codeowners +description: Use when working with aiconfigurator's generated CODEOWNERS - finding out who reviews a change, fixing a failing codeowners CI check, changing review routing, or granting an external contributor area-scoped ownership. Trigger when the codeowners check fails on a PR, a new directory is unclaimed, someone asks who reviews a path or PR, or review routing needs to change. +--- + +# AIC CODEOWNERS Operations + +The root `CODEOWNERS` is a build artifact generated from +`.github/codeowners/areas.yaml` (one entry per area mapping path globs to a +GitHub team). Never hand-edit `CODEOWNERS` - CI regenerates it and fails on +any drift. Every change goes through `areas.yaml` (or +`external_contributors.yaml`) followed by regeneration. + +## Flow 1: Who reviews this change? + +```bash +# owners of your working tree's changed files (union, as GitHub will request) +python .github/codeowners/who_owns.py --codeowners CODEOWNERS --changed + +# owners of specific paths +python .github/codeowners/who_owns.py --codeowners CODEOWNERS [ ...] +``` + +Add `--people` to expand each team to its member logins (org members with an +authenticated `gh` only; GitHub hides team membership from non-members). + +## Flow 2: The `codeowners` CI check failed + +The coverage gate is doing its job: the PR adds at least one file that no +area claims. + +1. Read the failing job log; the gate prints the exact uncovered files under + `catch-all-only sample`. +2. Add ONE line to `.github/codeowners/areas.yaml` under the owning area's + `path_globs` (directory claims end with `/`). +3. Regenerate and verify: + ```bash + python .github/codeowners/build_codeowners.py \ + --areas .github/codeowners/areas.yaml --repo . --strict + python .github/codeowners/emit_codeowners.py \ + --areas .github/codeowners/areas.yaml --repo . --out CODEOWNERS + ``` +4. Commit `areas.yaml` and `CODEOWNERS` together, signed (`git commit -s`). + +Removals fail the DRIFT step instead (deleting a directory never fails +coverage): run step 3 and commit both files, and prune the now-dead glob - +the coverage report lists globs that no longer match any file. + +## Flow 3: Change review routing + +Edit `.github/codeowners/areas.yaml` - move a glob between areas, add a +`shared:` entry (multi-team; any one team's approval satisfies the gate), or +adjust `classify` rules - then regenerate as in Flow 2. Changes to the +policy itself route to aiconfigurator-infra + maintainers (the `CODEOWNERS` +shared line). + +## Flow 4: Grant an external contributor area-scoped ownership + +Add an entry to `.github/codeowners/external_contributors.yaml` (name, +github, level, affiliation, `areas: [