Learning Kubernetes-isms: OWNERS files, approvers, and reviewers

The Kubernetes community has a number of Kubernetes-isms. That is, things specific to the Kubernetes community that those in the tribe know but may not be obvious to those outside or new to it. One such area is the notion of approvers, reviewers, and the use of OWNERS files scattered around the codebase. So, let's break down what's going on here.

Reviewers and Approvers

The Kubernetes community has a little bit of formality to it. People can become formal "members" of the community and take on different roles when it comes to interacting with parts of the code. This formality is laid out in community membership documentation (see at time of post publication and latest).

Two of those levels are reviewer and approver. For part of the codebase, which is a directory and all sub-directories of that location someone can have the role of a code reviewer or approver. These can be nested. For example, there may be a reviewer or approver for a whole repository while another set handles a sub-directory within that. It cascades.

A reviewer is someone who can review pull requests for that section of code. They have a bit of experience and can review pull requests because of that. By being a reviewer for a section of code they are signaling to others that they are currently signed up to review pull requests. When you need a pull request reviewed these are the go-to people.

An approver is someone who can accept contributions for a section of code. Not only can they review the code but they are trusted to merge code in. Approver is the next step up the community ladder from reviewer.

Owners Files

Files with the name OWNERS codify who the reviewers and approvers are. It's a YAML file (sorry no extension) that has lists for each set.

One thing to catch is that some names appear on both lists in an OWNERS file. This is because some approvers are active in reviewing while others are not. More on this in a moment.

Tooling

There is custom tooling in the Kubernetes community to support OWNERS files and the responsibilities of reviewers and approvers. For example, a reviewer be asked to review certain pull requests automatically. This is currently via assignment but in the future is planned to move to requested reviews. Note, this needs to specifically be turned on for a repo.

Reviewers can also accept a review by adding /lgtm in a comment on a pull request. If the person is a valid reviewer for that section of code a LGTM label will be added to the pull request and the tooling will know it passed a review.

Approvers have a similar piece of functionality. They can /approve a pull request to approve it. Or, they can /lgtm a pull request that will git it both the Approved and LGTM labels. Just like reviewers, the tooling only applies the labels if someone is in an OWNERS file responsible for a section of code.

Once something is approved and reviewed (in most cases since this is technically configurable on a per repo basis) a bot comes along and performs the merge.

Yes, the tooling does provide for an ACL system on top of GitHub and parts of a codebase.