Notation naming

[mattfarina]

If I understand things correctly, the spec here is for Notation rather than Notary v2. The repo being named notaryproject and the documentation referring to Notary v2 is confusing if that is that case. Can the repo name and documentation be clarified and updated.

[lachie83]

Thanks @mattfarina. We will make sure that this is discussed with the Notary community and cleared up.

[toddysm]

This item is added to the agenda for Notary community on March 6th. Agenda is available at https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw

[yizha1]

@mattfarina Here are some updates for Notation naming and other governance work we did these days.

• Notation naming
  • Fix the names in notation, notaryproject.dev and meeting-notes
  • Fix sub-projects: notation-go, notation-core-go
  • Fix sub-project: notaryproject, since notaryproject contains spec and requirements, it will take more time than code repo.
• Governance and contributing guide
  • Use and copy governance.md and contributing.md from notary repo to .github repo
  • Update these two documents to reflect the status and vision of notary project.
• Sub-repo governances
  • Create MAINTAINERS and CODEOWNERS for each sub-project
• GitHub Teams Governance
  • Create separated team for sub-projects and org maintainers
• Branch policies
  • PR and code review policies
  • release branch (Plan to do it for Notation first stable release)
• Security audit
  • fuzz testing report
  • security audit (6 weeks audit by OSTIF team and report will be ready by this week Apr 21)
• Notary project annual review (plan to start after notation v1.0.0-rc.4 release targeting this week Apr 21)

There are other works not listed here. All the governance related issues are tracked in one place: https://github.com/orgs/notaryproject/projects/10/views/32

cc: @FeynmanZhou @toddysm @vaninrao10 @shizhMSFT @priteshbandi @patrickzheng200 @JeyJeyGao @iamsamirzon @lachie83 @rgnote

[TheFoxAtWork]

@yizha1 thank you so much for the updates! Do you happen to have estimated timelines for the remaining outstanding items?

[yizha1]

@TheFoxAtWork Estimated timeline for the following items is by end of May. For CNCF annual review, the PR submission date is by end of Apr.

• Fix sub-projects: notation-go, notation-core-go
• Fix sub-project: notaryproject, since notaryproject contains spec and requirements, it will take more time than code repo.
• Update these two documents to reflect the status and vision of notary project.
• release branch policy
• security audit - Report will be ready by this week Apr 21
• Notary project annual review - submit PR to CNCF by Apr

Please let us know if you have any comments.

[toddysm]

@yizha1 we need to complete this one before 1.0.0 release. Please add to the milestone.

[yizha1]

Status updates on the remaining governance issues,

• Remove Notary v2 reference in notaryproject repository:
  • doc: update readme.md for the Notary Project #263
  • doc: remove Notary v2 reference #262
  • doc: update signature specification for v1 release #256
• Release branch policy
• Update contributing guide: doc: update contributing guide .github#25
• Security Audit: Security advisories were fixed and published. The security audit report is under preparation.
• Annual review: The content is under reviewing by the Notary community

[yizha1]

Here is the list of PRs to resolve this issue:

• doc: update signature specification for v1 release #256
• doc: remove Notary v2 reference #262

PR #263 to update Readme.md will be updated after the following PR is merged.

• Updated the README.md with overview details .github#32

Other Governance issues are tracked by the board

[TheFoxAtWork]

I've gone through the linked PRs (and a few others). Some high level areas of improvement still needed:

• Terminology - there are terms used through out that are unique to the Notary Project specification and Notary Project itself that are undefined and introduce confusion.
• Notary and Notary Project appear to be used interchangeably throughout several files - it is unclear if any references of "Notary" be they "Notary signature" or "Notary signature specification" actually refer to Notary or if they refer to Notary Project except when they are linked (for a casual reader it would require clicking through to the link in order understand the difference)
• Notation - if Notation is indeed the implementation of the Notary Project signature specification, would it be simpler to refer to the specification as Notation as well? This would avoid any confusion with Notary versus Notary Project regarding signatures and signature specifications.

[sudo-bmitch]

Notary describes itself in several places as the Notary project. I agree with @TheFoxAtWork , a reasonable person would confuse the Notary project with The Notary Project.

Instead of renaming Notary v2 to The Notary Project, I'd propose calling it notation-spec. That would be more clear for end users looking for the spec of either notary or notation which spec this repository is providing.

[yizha1]

Thanks @sudo-bmitch for the feedback. Would you mind take a look at this PR under .github repo notaryproject/.github#32? Hope it clarifies the changes. After this PR is approved and merged, we will update readme.md of each repository, so that users will know what the Notary Project is (referring to the one in .github) and what is the overview of the specific repository. Let us know if you have further questions.

[yizha1]

@mattfarina @TheFoxAtWork Could you review this PR notaryproject/.github#32 again since some comments are resolved? Hope the latest update clarifies your questions. After this PR is approved and merged, I will create PRs to update readme.md in each repo for clarification what the Notary Project is, and what the specific repo is. Thanks.

[yizha1]

@mattfarina @TheFoxAtWork This issue was closed automatically due to three related PRs were merged, see

• doc: update signature specification for v1 release #256
• doc: remove Notary v2 reference #262
• doc: update readme.md for the Notary Project #263

The repo name is now specifications based on the votes of this issue notaryproject/.github#38.

The naming work on this repo was done. Regarding Notary Project overall naming issue, we have this issue to track the Notary Project naming https://github.com/notaryproject/.github/issues/35, where relevant PRs were also listed.

Thanks for your support.

[TheFoxAtWork]

Thank you!!