``` + notaryproject (organization) - notaryproject-org-maintainers (team) + notaryproject (repository) + notaryproject-repo-maintainers (team) Note: Includes notaryproject-org-maintainers (team) - Role: Admin + notaryproject-repo-release-managers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications - Role: Maintain + notaryproject-repo-code-reviewers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews - Role: Write + notaryproject.dev (repository) + notaryproject.dev-repo-maintainers (team) Note: Includes notaryproject-org-maintainers (team) - Role: Admin + notaryproject.dev-repo-release-managers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications - Role: Maintain + notaryproject.dev-repo-code-reviewers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews - Role: Write + notation (repository) + notation-repo-maintainers (team) Note: Includes notaryproject-org-maintainers (team) - Role: Admin + notation-repo-release-managers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications - Role: Maintain + notation-repo-code-reviewers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews - Role: Write + notation-go (repository) + notation-go-repo-maintainers (team) Note: Includes notaryproject-org-maintainers (team) - Role: Admin + notation-go-repo-release-managers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications - Role: Maintain + notation-go-repo-code-reviewers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews - Role: Write + notation-core-go (repository) + notation-core-go-repo-maintainers (team) Note: Includes notaryproject-org-maintainers (team) - Role: Admin + notation-core-go-repo-release-managers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications - Role: Maintain + notation-core-go-repo-code-reviewers (team) Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews - Role: Write ```

Notary v2 Project Governance Improvements

For new contributors to the Notary project it is hard to understand the governance structure of the project, navigate the relevant repositories and understand the purpose for each repository and practices used for each piece of the project.

Few examples of the confusion are the following:

Notary Project has a notaryproject repository that may be the logical place to go with when browsing the organization and trying to learn about the project. However, this repository does not contain any Governance information in it; it is intended for specs only.
Governance information (GOVERNANCE.md documents) is available in the notary repository, which has the legacy Notary code. Other repositories have Code of Conduct, Contributing, and Release Management documents but those are inconsistent and introduce more confusion.
Notes and meeting recordings are inconsistent. While capturing meeting notes is done consistently it seems the recording are not posted on a regular basis (Note: recordings are available in Zoom but they require the manual posting to YouTube, which is tedious). In the meeting notes on Hackmd.io there is a link to YouTube playlist but the last video is more than a year ago. Also, the meeting notes post confusing links to old notes archives. Last, but not least, the meeting notes not always capture the attendees and the decisions that are made. Recent examples are the notes from 2022-11-21, 2022-11-28, 2022-12-12, 2022-12-15, 2022-12-19. Without detailed meeting notes and lack of videos, the transparency in the community is reduced and folks need to attend the meetings to understand the project development.

This has impact on the branding, the communication as well as of the security of the project. To improve the governance of the project, I would like to propose the following.

Clean up the repositories

We should clearly define the purpose of each repository under the organization and update the descriptions of the repositories to reflect that purpose. Also, if there are repositories that need to be archived, we should do that. For example, the notary and tuf have very little activity and may be good candidates for archival. Of course, we need to get the maintainers of the respective repositories to do that.

The rest of the repositories have the following purpose:

notaryproject is intended for the Notary v2 specification. The information in this repo should be targeted to people who are interested to understand and influence the specification and not necessary contribute code to the libraries and tools.
notaryproject.dev is intended for the web-site content
notary-core-go is intended for the library with the core crypto functionality.
notary-go is inteded for the wrapper library that uses the notation-core-go and other libraries like oras-go to do the signing and interact with the registries.
notation is inteded for the thin wrapper around the library that provides a CLI
meeting-notes is inteded for the archiving the meeting notes
roadmap is intended for project management purposes only

For each repository, we should have the following documents:

See below for updates to those documents.

Update the Governance documents

CODEOWNERS

We need to have owners for the Organization as well as for each individual repository. Those do not necessarily need to be the same.

GOVERNANCE.md

As an example, I am linking the Kubernetes Governance document. We may want to scale down as a smaller project but we need to at a minimum address the following questions in the GOVERNANCE.md document:

What are the principles we follow?
What are the Notary community values?
What is the governance structure of the project? WGs, SIGs, committees, user groups, subprojects, etc. How are those created? How are they managed? What are the processes for those? How does one become a member? etc.
Note: This is at the core of the governance and helps people understand how can they engage with the project and what is the process for that.
List to the WGs, SIGs, etc. as well as responsible people in those(chairs, maintainers).
How are chairs rotated, selected, etc.?
Provide details how accountability for the project is handled?
How to contact maintainers/owners?

We can have a single GOVERNANCE.md document with all the content and separate GOVERNANCE.md documents in each repository that link to the full one and eventually outline any specifics for the respective repository.

Cleanup the MAINTAINERS file as it still references:

This file describes who runs the theupdateframework/notary
which is where the notary repo was prior to the TOC resolution in July 2021

CONTRIBUTING.md

I am linking the Helm contribution guidelines as an example. Address the following questions in the CONTRIBUTING.md document:

What is the license agreement for contribution?
How we use semanting versioning?
How to contribute content/code? Signing, conventions/code guidelines, how to create a PR, how to comment on commit, how to file issue, how to file a feature requests etc.
How to get in touch for questions or help?

Also, we need to make sure that each repository has the necessary templates for filing issues and feature requests.

SECURITY.md

This should be the document describing how to file security issues. I am linking the Helm security policy document as an example.

We should make sure that we use the GitHub Security Issues reporting process but we still need to have a document describing what the process for review of those issues are and what are the timelines to handle and respond to an issue or vulnerability. We should also have a place where we post the responses to those issues. Other things to cover here are:

Disclosures - how are those published
Responsibilities - who are the responsible members and what their responsibilities are
Reports - guidance for what needs to be included in the vulnerability report

RELEASE-MANAGEMENT.md

We have a simple RELEASE_MANAGEMENT.md and RELEASE_CHECKLIST documents for notation (though, they can be combined in one). They address some of the points below. But in general, the release management should describe the process of release for each one of the sub-projects (CLI, libraries). As part of the release management process, we should address the following:

Versioning and the guidance for versioning (semantic - major, minor, patch)
Process for different releases (major, minor, patch) - who can approve a specific release?
How long releases are supported? (Maybe, we need a separate SUPPORT-POLICY.md for that)
What are the steps to make a release? (the RELEASE-CHECKLIST.md)
What needs to be included in the RELEASE-NOTES.md?

Guidance for taking meeting notes

To increase the transparency, we should follow more strict notes-taking process. At a min, we should have the following:

Up to date list of rotating meeting chairs
Always accurate name for the meeting chair for each meeting (those may chainge between meetings and from the current meeting notes it is not clear who chaired the meeting)
Always accurate list of attendees and their affiliation
Always accurate list of agenda items
Captured notes from each meeting
Captured decisions from each meeting
Meeting notes must always include a link to the posted vide

Also, we need to make sure that meeting notes are not changed after they are completed. HackMD allows changing the notes but keeps versioning and audit trail for up to 10 changes for free users. To avoid the HackMD limitations, we may want to change the process we use HackMD. For example, using a new HackMD document for each meeting to avoid the perf issues with growing docs and linking to the documents from an MD document on GitHub.

The above process should be added to the responsibilities to the meeting chair.

Addressing the security of the Notary Project

For this we need to split the security in two parts: teams and branch security.

Teams

If we use the current organization and repo structure, I propose the following teams structure:

+ notaryproject (organization)
    - notaryproject-org-maintainers (team)
    + notaryproject (repository)
        + notaryproject-repo-maintainers (team)
          Note: Includes notaryproject-org-maintainers (team)
            - Role: Admin
        + notaryproject-repo-release-managers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications
            - Role: Maintain
        + notaryproject-repo-code-reviewers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews
            - Role: Write
    + notaryproject.dev (repository)
        + notaryproject.dev-repo-maintainers (team)
          Note: Includes notaryproject-org-maintainers (team)
            - Role: Admin
        + notaryproject.dev-repo-release-managers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications
            - Role: Maintain
        + notaryproject.dev-repo-code-reviewers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews
            - Role: Write
    + notation (repository)
        + notation-repo-maintainers (team)
          Note: Includes notaryproject-org-maintainers (team)
            - Role: Admin
        + notation-repo-release-managers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications
            - Role: Maintain
        + notation-repo-code-reviewers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews
            - Role: Write
    + notation-go (repository)
        + notation-go-repo-maintainers (team)
          Note: Includes notaryproject-org-maintainers (team)
            - Role: Admin
        + notation-go-repo-release-managers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications
            - Role: Maintain
        + notation-go-repo-code-reviewers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews
            - Role: Write
    + notation-core-go (repository)
        + notation-core-go-repo-maintainers (team)
          Note: Includes notaryproject-org-maintainers (team)
            - Role: Admin
        + notation-core-go-repo-release-managers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications
            - Role: Maintain
        + notation-core-go-repo-code-reviewers (team)
          Note: Includes at least two of the leading members from different orgs participating in the development of the specifications. This team should automatically be assigned for PR reviews
            - Role: Write

Branch security

For the branch security, we should implement the following restrictions:

Pushes to main and release branches must have PR with at least 2 approvals. Direct pushes to main and release branches must be disallowed
Restrict who can push to matching branches (release managers)
Signed commits are required
Require conversation resolution before merging
Do not allow bypassing the restrictions

Updating Documentation

Much of the guidance here is based on the way the Open Service Mesh docs handle documentation updates, releases, and localization.

A contributors.md file in notaryproject.dev will define the contribution process, but, in short, contributors should fork the repo and have their PRs target the main branch.
Release branches will be created off of the main branch, e.g. release-v1.0, and published as a subdomain of the docs site, e.g. release-v1.0.notaryproject.dev/docs
Outside of applying a patch or localization to a specific doc after release, PRs should only target main after a release branch is published
The main docs url, i.e. notaryproject.dev/docs, will redirect to the latest release subdomain
A version of main can be published, but only for preview purposes. Offically published docs need to correspond to a release branch
Larger or significant docs PRs should have at least 2 approvers that are maintainers
Smaller PRs, e.g. typo fixes, only need 1 approver
Localization must be done by hand for each release. Localization PRs should target specific release branches and never main. Localization scaffolds are intentionally empty in the main branch

Pritesh Bandi

2023/01/12 05:53:27

oadmap](https://github.com/notaryproject/roadmap)

Do we need roadmap repo can we projects like https://github.com/orgs/notaryproject/projects/10 ? (Edited)

2023/01/12 05:54:16

is inteded for the thin wrapper around the library that provides a CLI

nit a thin wrapper around notation-go to provide CLI (Edited)

2023/01/12 06:02:02

SIGs

What is SIG? (Edited)

2023/01/12 06:26:12

Whats the permission difference between *-managers and *-reviewers team? (Edited)

2023/01/12 06:26:54

following teams structure

We should also look at who all has permissions to merge to main; as of now its pretty open. (Edited)

2023/01/12 17:28:50

Can we add details about the team and permissions for each one of them

2023/01/12 17:29:34

also can we optimize on teams for 3 repo and have same tem for notation repo

2023/01/12 06:27:21

matching branches

What does matching means here? (Edited)

toddysm

2023/01/12 20:57:34

Special Interest Group. A Working Group (WG) can be created to decide whether something fits in the project's charter. If the decision is "yes" and it is accepted in the project, then it becomes SIG to drive this forward (Edited)

2023/01/12 20:58:39

Updated the text (Edited)

2023/01/12 20:59:21

Samir wanted to use the roadmap repo to drive the roadmap. Would like his feedback here. (Edited)

2023/01/12 21:25:27

Yes, let me work on that and add more details. I may prototype this in a separate GitHub repo (Edited)

2023/01/12 21:27:14

Here is a link to the GitHub permissions: https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role (Edited)

2023/01/12 21:32:33

This is related to protecting other branches like release branches in addition to the main branch. Here details: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#restrict-who-can-push-to-matching-branches (Edited)

Samir Kakkar

2023/01/12 21:49:22

inteded for the wrapper

Notation-go abstraction allows other projects or clients ( like Ratify) to leverage Notation as a library Vs as CLI client (Edited)

2023/01/12 21:59:03

I can go either way. I believe removing will be more work. Having a roadmap repo is a common pattern. Refer https://github.com/github/roadmap (Edited)