Add governance description for OWNERS and MAINTAINERS files within each repo

[SteveLasker]

We've recently added OWNERS and MAINTAINERS to each repo, attempting to create clarity for who has rights to the repos.
While it would be nice for Github teams to capture this in a declarative format, it's the tools we have today.

This is a tracking issue to define what Github roles are associated with the OWNERS and MAINTAINERS files within the notaryproject Governance docs.

As part of the PR, how do folks want to capture Org maintainers? Should that also be captured in the OWNERS and MAINTAINERS file for full transparency? Or, is that captured in org governance?
For reference: notation/MAINTAINERS and notation/CODEOWNERS

Copied from: oras-project/community: Add governance description for OWNERS and MAINTAINERS files within each repo #47

[toddysm]

We don't need OWNERS, CODEOWNERS, and MAINTAINERS files. I agree that this information should be captured in the governance. The definition of the files is as follows:

CODEOWNERS
Lists the GitHub handles of the maintainers for the repository and it is automatically used to assign approvals for PRs. The branch policies use the CODEOWNERS file to ensure that necessary approvals are provided for PR to be merged.

Note: The CODEOWNERS file is the one that GitHub uses for the PRs. See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

Because the CODEOWNERS file doesn't list real names and contact information for maintainers, we agreed to have MAINTAINRS. The definition is:

MAINTAINERS
Maintainers file is used to list the GitHub handles, emails, real names, and eventual association of the maintainers of the repository.

OWNERS file is not needed.

Hope this helps.

[yizha1]

We've recently added OWNERS and MAINTAINERS to each repo,

@SteveLasker Maybe you mixed the OWNERS and CODEOWNERS.

• CODEOWNERS are clearly defined here https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
• OWNERS if you refer to my issue Add OWNERS for each sub-project #13, it means the Admin role, as defined here https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization#repository-roles-for-organizations. Maintainers can have both Maintain and Admin roles.

[toddysm]

The linked article explains the permission model that is implemented in GitHub. It does not specify any need for OWNERS file. It does link to the CODEOWNERS file that is the only one that has significant importance in GitHub as of now.

Let's not confuse things and just use the two files that we have already created for each repository. Those two files are CODEOWNERS and MAINTAINERS.

The ask from @SteveLasker to have their description added to the governance is still valid.