Feedback on OWNERS file

[bkeepers]

Knowing who owns a project or piece of code is often tribal knowledge, which makes it difficult to know who to ask for help, feedback, or review.

I would love feedback on this proposal for an OWNERS file, which is a human and machine readable format that specifies who is responsible for maintaining a project or specific files in a project, and may be used to notify maintainers of modifications or to enforce approval in reviews.

$ cat OWNERS
# Specify owners by email address.
user@example.com

# …or GitHub username
@username

# …or GitHub team
@org/team

# …and even limit to specific paths
@org/js *.js
@org/legal LICENSE*

Not only does this communicate who is currently responsible for the project, it could also be used to suggest who to CCs on pull requests. Someone that wants to keep up with specific parts of the code on a very active project could add their name to the OWNERS file with a glob of the files they care about.

What do you think?

/cc bkeepers/dotenv#198 for an example
/cc @josh @MikeMcQuaid @benbalter

[jasonkarns]

seems this information is already present in repos for (some) ecosystems. In node, there is the author and contributors fields in package.json as well as the maintainers info on the npm registry: e.g. https://www.npmjs.com/package/lineman/access.

Ideas on how the info could be shared without being duplicated?

[laserlemon]

Love the idea. I share @jasonkarns' concern about duplication but I think it's reasonable to expect that the owners listed in OWNERS may differ from those in a gemspec.

[bkeepers]

Ideas on how the info could be shared without being duplicated?

As @laserlemon alludes to, I think the information in package.json/gemspec/etc may serve a slightly different purpose, such as attribution. OWNERS is intended to reflect who currently maintains the project.

[jacobbednarz]

Great idea! This would be great to see some integration on GitHub (if a name or team was included in the OWNERS file). Example, you have the following OWNERS file:

@org/frontend *.js

When opening your pull request for changes to javascript files it could display a notice like "Perhaps you should include @org/frontend?".

[benbalter]

Rather than creating a new standard, what about adopting/extending the Humans.txt format?

[josh]

🤘

[gjtorikian]

Rather than creating a new standard, what about adopting/extending the Humans.txt format?

The OWNERS/MAINTAINERS file convention has been around for a long time. Here's Linux core's from 2005.

/cc @thoward as we were just talking about this.

[thoward]

I think one key difference is whether or not the file is meant to be machine readable, or human readable.

At Twitter, we use OWNERS files in subpaths to describe ownership of that subpath. It's primarily used in a machine-readable context, by internal tools such as review/CI process. I'm pretty sure this is a Google-ism that we inherited from folks we hired from there. We also use a GROUPS file when group ownership is relevant (though this is used pretty sparsely). Our files are very simplistic, containing only a single LDAP username (or group name) per line. We also support wildcard *, however there are no @ symbols in our usernames. A minor difference.

The Linux MAINTAINERS seems to be focused on human-readable, with lots of free-form prose without any sort of comment demarcation, though it looks parseable as well.

The humans.txt format seems to lean a bit more parseable, but still rather free-form, and thus more focused on human-readable use case vs machine readable.