Context
The repository had accumulated several different kinds of governance documentation in overlapping places:
- Plans described proposed Entra ID, GitHub Team, and CODEOWNERS structures
- Some of those plans were later implemented only partially or in a simplified form
- Active documentation and automation began referring back to plans as if they were the current source of truth
This made it too easy for a historical plan to be mistaken for the live operating model.
At the same time, the proposed ownership model had become more granular than the current organisation needed. Maintaining product-specific and value-stream-specific security groups and GitHub teams would create ongoing administrative overhead without enough operational benefit.
Decision
We will separate governance documentation into three clear categories:
-
Plans (
content/00 Governance/Plans/)- describe proposed work, migration steps, or implementation thinking
- remain as historical planning artefacts once completed or superseded
- are not the canonical current-state reference
-
Decision records (
content/00 Governance/Decisions/)- capture why a material governance or architecture choice was made
- record trade-offs and consequences
-
Current-state reference docs (
docs/)- capture what is actively configured and expected now
- are the canonical reference for operational ownership and review routing
For repository ownership specifically, the active model is now:
- guild-first review ownership by default
- a single practice-specific exception for Security Mgmt
- no active product-specific or value-stream-specific GitHub review teams
Consequences
Benefits
- Lower operational overhead: fewer groups and team mappings to maintain
- Clearer documentation lifecycle: plans, decisions, and reference docs have distinct roles
- Less drift: automation and active docs can point to a stable current-state file
- Easier onboarding: contributors can find the live model without interpreting historical plans
Trade-offs
- Historical plans may no longer match the active model line-for-line
- Future changes require updating both the current-state reference and the relevant decision record
- Some previously planned automation paths need to be simplified to match the active model
Related
docs/OWNERSHIP_MODEL.md.github/CODEOWNERScontent/00 Governance/Plans/10 Entra ID & GitHub Teams Integration/README.md