CODEOWNERS.md vs Authors.md

[mgifford]

I don't understand the Code Owner distinction. Particularly on a non-code project. Isn't Author more generic?

I guess that your CODEOWNERS.md blends together the author and contributor roles.

This is how we did it here:
https://github.com/GSA/openacr

For US government contracting I do think it is important to separate who would be the legal owner, vs who did the work. Least I think that it matters. In the case of OpenACR, CivicActions did 90% of the work on the repo, but we were doing it in contract to the GSA.

CODEOWNERS.md is not a distinction I've seen before in other repos.

[decause-gov]

@mgifford Thank you for sharing :)

Here's our thinking out loud: https://github.com/DSACMS/repo-scaffolder/blob/main/maturity-model-tiers.md

CODEOWNERS.md is recommended docs for Tier2, mandatory for Tier3, meant to show to who are the points of contact for the code generally, like business owners or teams. This group is not necessarily the group of developers or contributors you would tag in an issue, but the folks you would follow-up with after the development team has moved on (as it so often does in the often contractor-driven world of Federal repos.) CODEOWNERS.md is a practice I've often seen in private-sector or Innersource style repos.

MAINTAINERS.md is a recommended Tier2, mandatory Tier3 doc. Tier3 projects set an expectation that the code base will continue to receive updates, possibly even contributions from outside of the core team. I've seen this patterns more often in the project-based community world of open source. This doc does include which groups of developers you would tag in what parts of the code for reviews.

AUTHORS.md contains the kind of attribution information that we would generate in this section of MAINTAINERS.md, where we recognize who has contributed to what: https://github.com/DSACMS/repo-scaffolder/blob/main/MAINTAINERS.md#contributors

We're experimenting with taking some pieces of all these different practices and including them here. Hope this is helpful, happy to discuss further, thank you for your contributions to the conversation.

[decause-gov]

@mgifford after taking some time to consider your issue, we recently updated our repo-scaffolder templates with a new approach: COMMUNITY.md

(See #267, specifically: https://github.com/DSACMS/repo-scaffolder/pull/267/files?short_path=62ebf46#diff-62ebf46315a443b29867d150272ea3bb5910b14098773249779bdadfe2df5f8c)

This PR:

Moved CODEOWNERS.md to .github for tiers 2-4
Removed MAINTAINERS.md for tiers 2-4
Added code.json to tables
Added COMMUNITY.md with sections
Deleted workflows.md and replaced with .github-directory.md explaining all files and workflows.

We moved COMMUNITY_GUIDELINES and MAINTAINERS.md into one file, and moved CODEOWNERS.md into the .github directory where GitHub expects it to be to take advantage of the autotagging features of the platform.

Our COMMUNITY.md file includes sections for folks like "ALUMNI" of the project, and allows for non-developer contributors to be listed at the top of the file along with devs. Our cookiecutter configs also support populating this new information too :)

Would love to hear your thoughts on how you think we did walking the middle road here :)