I propose this tool generates a good template to start with, which include human readable rules and instructions. I will share the one I have written for @OpenGov as a basis for discussion and improvement.
Reasons
GitHub provides exceptionally poor documentation
Over the last year of working with them over many different codeowners issues, their support has implicitly assured me they are not going to improve it and don't take it very seriously, even as they promote infra as code, where a missing code review could be the difference between success and calamity.
Template
For discussion. This is what I inferred from practice.
###
# Keep this organized alphabetically by team (except where noted),
# read the NOTES, and leave meaningful comments.
# ----------------------------------------------------------------
#
# NOTES ABOUT HOW THIS FILE WORKS
# - Validate all changes with https://github.com/mszostok/codeowners-validator
#
# - Most rules should start with a slash unless you intentionally
# want ownership of that pattern _anywhere_ in the repo.
# Leave a comment if this is the case.
#
# - The last matching rule is the one applied. Examples:
# 1) CoreTeam takes ownership of all files with * at the top,
# and any rule below for another team will take precedence.
# 2) CoreTeam is the last listed owner/match for things like Dockerfile
# and helm, so it will be the owning team for changes to those files
# even if they're part of another team's service in a higher match.
#
# - As a result of the matching rules above, DO NOT ADD ! (negation) rules.
#
# - The base branch's CODEOWNERS file takes precedence over changes
# to the CODEOWNERS files in a branch, meaning you can't remove
# a base team without their approval.
#
# - Changes to CODEOWNERS in a branch are reflected in the PR,
# meaning newly added teams will be requested for review in the PR.
#
# - Reviewers only get updated when a push occurs to the branch.
#
# - ALL TEAMS MUST BE EXPLICITLY GIVEN WRITE ACCESS TO THE REPO
# (or they must be a child team of a team that has write access)
# ----------------------------------------------------------------
#
# RESOURCES
# - https://git-scm.com/docs/gitignore#_pattern_format
# - https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners
# ----------------------------------------------------------------
###
###
# CoreTeam is the default owner if no one else takes ownership below.
# This is to ensure that someone owns everything eventually.
#
# DO NOT MOVE THIS FROM THE TOP OF THE FILE.
###
* @CoreTeam
###
# SubTeam
###
/source/bar-service @SubTeam
# !!! KEEP CoreTeam LAST !!!
# (These are overrides.)
###
# CoreTeam
###
# All root dotfiles.
/.* @CoreTeam
# All repository integrations with GitHub.
/.github @CoreTeam
# All .gitignores
**/.gitignore @OpenGov/CoreTeam
Description
I propose this tool generates a good template to start with, which include human readable rules and instructions. I will share the one I have written for @OpenGov as a basis for discussion and improvement.
Reasons
Template For discussion. This is what I inferred from practice.