---
# System prepended metadata

title: Repository Level Ownership

---

# Repository Level Ownership

# Meta
[meta]: #meta
- Name: Repository Level Ownership
- Start Date: 2022-04-14
- Author(s): @jromero
- Status: Draft
- RFC Pull Request: (leave blank)
- CNB Pull Request: (leave blank)
- CNB Issue: (leave blank)
- Supersedes:

# Summary
[summary]: #summary

Migrate to using `CODEOWNERS` files to identify repository ownership across the entire project.

# Definitions
[definitions]: #definitions

- sub-teams: Group of individuals focused on narrower sets of concerns related to specific aspects of the project.
- maintainers: Individuals that maintain specific code reporitories.

# Motivation
[motivation]: #motivation

The current maintainer model is not ideal for contributors that want to focus on only a single component without taking on responsibilities for all other repositories. By attributing repositories to individual owners, sub-teams can better manage lower-level ownership models.

As a consumer, it becomes easier to identify individuals responsible for each repository if the repository had a reference to the "owners" of the repository.

# What it is
[what-it-is]: #what-it-is

A `CODEOWNERS` file in each project repository that identifies individuals and/or teams responsible for the repository.

Individuals will be referenced by their GitHub username handle while teams would be referenece by GitHub Team handles.

```CODEOWNERS
# GitHub team
* @buildpacks/platform-maintainers

# individual
* @jromero
```

# How it Works
[how-it-works]: #how-it-works

Instead of a list of repositories and ownership listed in a central place (currently [GOVERNANCE.md][gov]) each repository within the project will contain a `CODEOWNERS` file that lists owners for that particular repository.

It is recommended that each repository `CODEOWNERS` file have at least one GitHub team owner as a "fallback" in case any individuals are unreachable.

# Migration
[migration]: #migration

- Remove list of repositories from [`GOVERNANCE.md`][gov].
- Maintainers of current repositories should identify owners and create an `OWNERS` file in each repository.

[gov]: https://github.com/buildpacks/community/blob/main/GOVERNANCE.md

# Drawbacks
[drawbacks]: #drawbacks

# Alternatives
[alternatives]: #alternatives

- Continue to expect ownership of repositories to be only at the sub-team level.
- Use _custom_ `OWNERS` and `OWNER_ALIAS` files instead of relying on GitHub specific functionality/standards.
    - K8s does this:
      > "We use aliases for groups instead of GitHub Teams, because changes to GitHub Teams are not publicly auditable."

# Prior Art
[prior-art]: #prior-art

- [K8s' OWNERS](https://www.kubernetes.dev/docs/guide/owners/)
- [Chromium's OWNERS](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/code_reviews.md#owners-files)
- [GitLab's CODEOWNERS](https://docs.gitlab.com/ee/user/project/code_owners.html#set-up-code-owners)

# Unresolved Questions
[unresolved-questions]: #unresolved-questions

- Do owners have to be sub-team maintainers?
    - This question is out-of-scope of this RFC and would require a larger more impacting governace change and discussion.
- How are permissions handled?
    - At this point in time, it's proposed that maintainers and leads take the appropriete actions necessary to ensure parity. This can easily be automated once adopted.