Proposal for bringing clarity to the Notary Project branding

[toddysm]

@notaryproject/notaryproject-governance-maintainers In the last Notary Project meeting (notes and meeting recording) we discussed how to clarify the branding of the Notary Project and make it clear to people who are interested to use the tools and participate in the community what means what. This is related also to the following two items notaryproject/specifications#262 and #32.

In the meeting, we discussed the following changes, which I am posting here for discussion by maintainers.

1. Archive the notaryproject repository and create a new repository called specifications that will contain the specifications that are across any tools as well as used by any external tools or projects that want to interoperate with our tools.
   1.1 Inside the new repository, we will structure the specifications in folders to provide more clarity. Right now, we have two main specification areas - one for signatures and signing workflow for OCI artifacts, and one for Notation plugin implementation. Those should be in separate folders. In the future, we will have more specifications that will be placed in their own folders. Each folder will have a README.md to explain the purpose of each document inside the folder.
   1.2 The repository will have its own README.md to explain the purpose of the repository as well as link to the READMEs in each individual folder.
   1.3 Current notaryproject repository contains folders for requirements and scenarios. Requirements can be captured as GitHub issues in the future and scenarios can be documented in the GitHub issues, HackMD documents linked from the GitHub issues or on the project's website in notaryproject.dev repository. Hence, the proposal is to not move those to the new repository.
   1.4 Current notaryproject repository contains the latest security reports. The latest security reports cover multiple repositories under the organization. Note: there are also some security reports in the notary repository that are specific to the implementation in that repository. The proposal is to migrate the latest security reports and the threat model to the .github repository and create a relevant directory structure in it. Also, to link to the security reports from the READMEs of the relevant repositories they cover.
2. We need to update each individual repository README.md with the following information: link to the overview, purpose of the repository, is it in active development or not, is it archived or not.
3. We need to have a process for archiving repositories under the organization and make sure that we clean up all repositories before the release.

We also discussed to acknowledge the terminology we use and how should we use it. The confusion comes from the use of terms like "Notary", "Notary V2", "Notary Project", "Notation". Here is the proposed (very draft) language:

1. The name of the GitHub organization is "Notary Project". When used this term has an all-encompassing meaning and will refer to the GitHub organization, the community, all specifications, and all the repositories under the organization including tools that are released by the community. Because this term is too broad, it is recommended to always use it with additional clarifiers unless we mean all of the above. For example, "Notary Project's signature specification" or "Notarty Project's signing workflow" or "Notary Project's Notation tool" (see about the last one below). The term should be used as an encompassing brand.
2. The name "Notary" refers to the TUF-based implementation from the notary repository. This is the only meaning of that term and we should use it only if we mean the TUF-based implementation.
3. The name "Notary V2" or "Notary v2" has no corresponding implementation or any relevant assets under the organization. Thus, this name is unclear and has no clear meaning for anything that Notary Project community collaborates on. Hence, this name should not be used in any context relevant to our work.
4. The name "Notation" refers to the implementation of the CLI and the libraries in the notation-go and notation-core-go repositories. If not clarified, the term "Notation" will mean the CLI. Of course, the CLI meaning can be clarified with "Notation CLI". If we want to address the libraries, we should always clarify with the corresponding library in mind. For example, "Notation Go", respectively "Notation Go library" for the library in the notation-go repository as well as "Notation Core Go", respectively "Notation Core Go library" for the library in the notation-core-go repository.
5. The term "Notary Project release" is also confusing because it doesn't clarify what is released (see above for the meaning of the term). We should use specific clarifiers for the releases. For example "Notary Project's signature specification release" or "Notary Project's Notation CLI release" or simply "Notation CLI release".
6. Last but not least, we would like to propose a change in the Notary Project logo to include the word "Project".

Note that the release of the specs and the Notation CLI are contingent on the branding changes that we describe above. I am appealing to the maintainers to take an active role in discussing and agreeing on the changes as soon as possible.

CC:// @TheFoxAtWork and @mattfarina for your feedback and comments on the above.

[toddysm]

One additional thing that was brought to my attention - the concepts of sub-project and working-group would be very helpful in clarifying the use of the repositories and terminology. Notary, Notation, Notation libraries are good candidates for "sub-projects" of Notary Project.

[toddysm]

Updated the issue to use numbered list as per suggestion from @iamsamirzon on the Notary Project community call.

[sajayantony]

SGTM and thank you @toddysm +1 on getting the terminologies sorted out. As per the call my understanding is that we would prioritize the terminology PR so that we can document these in #32.
Recommend other @notaryproject/notaryproject-org-maintainers to please comment with an LGTM or comment on this issue if there is any concern on this.

[yizha1]

LGTM

Thanks you @toddysm for the proposals. I would like to work with other maintainers of each repository to update the repo readme.md file based on this issue and #32, and review current governance documents on archiving repositories.

[Two-Hearts]

LGTM. Thanks @toddysm for the proposal!

[Miranlfk]

LGTM.

Would appreciate to see the terminology and branding improvements suggested by @toddysm to reduce/remove any confusion for users and community members.

[FeynmanZhou]

@toddysm Thanks for putting things together. The proposal of clarifying project terminology and archiving/restructuring the notaryproject repository is reasonable and doable. It's worth documenting these terminologies on https://notaryproject.dev/. I am happy to help.

[FeynmanZhou]

Given that we are close to the Notation v1.0.0 release, I would suggest fixing the naming/terminology issue before Notation v1.0.0 but finalizing the notaryproject cleanup after v1.0.0.
IMO, archiving/refactoring the notaryproject repository will not be a blocking issue for releasing Notation v1.0.0 and it could be marked as the first priority after v1.0.0. It will not block users to use Notation v1.0.0 in production. We could work in parallel to document the archiving process mentioned in #36 , archive notaryproject repo, and create a new specifications repo accordingly.

[shizhMSFT]

LGTM and thank @toddysm for putting all the things together.

[TheFoxAtWork]

1.3 Current notaryproject repository contains folders for requirements and scenarios. Requirements can be captured as GitHub issues in the future and scenarios can be documented in the GitHub issues, HackMD documents linked from the GitHub issues or on the project's website in notaryproject.dev repository. Hence, the proposal is to not move those to the new repository.

Requirements may be captured as GH issues however it may also be prudent to record high level 'requirements' or design principles as Scoping Goals/ Guide that the project and its community members may continuously refer back to when determining overall features, design criteria, and the acceptable characteristics for PRs.

We need to update each individual repository README.md with the following information: link to the overview, purpose of the repository, is it in active development or not, is it archived or not

Falco has a fantastic example of how they captured this, I highly recommend taking a look and adopting a version of it.

We need to have a process for archiving repositories under the organization and make sure that we clean up all repositories before the release.

Recommend this be included as a dedicated governance file for Archiving. Each repo should link back to that governance file. It should also include how the determination for Archive occurs and detail how Archival (once determined) is executed.

"Notary Project" ... The term should be used as an encompassing brand.

Wonderful, please make sure this is apparent on the documentation with an initial link back to the definition of what that encompasses the first time the phrase is introduced in repos.

prioritize the terminology PR so that we can document these in #32.

Agreed. The sooner terminology can be updated, the faster the project may move forward. I've made comments on PR 32 prior to reviewing this issue. Please consider those comments superseded by the decisions from this issue as appropriate.

Thank you all so much for taking the time to record this discussion's outcomes and recommendations. This will greatly assist new contributors and potential adopters at understanding this Project's varied repositories, goals, and objectives.

[FeynmanZhou]

Recommend this be included as a dedicated governance file for Archiving. Each repo should link back to that governance file. It should also include how the determination for Archive occurs and detail how Archival (once determined) is executed.

Thanks @TheFoxAtWork . I would like to create a dedicated file to clarify the repository lifecycle and archiving process in this repo.

[FeynmanZhou]

I sent a PR to clarify the repository lifecycle and the process of archiving a repository. PTAL #37

[NiazFK]

IMO the terms "Notary Project's signature specification" or "Notary Project's signing workflow" or "Notary Project's Notation tool" are overly complicated and confusing, specially for end users. Signature specification and workflows are specific to the TUF (Notary) and non-TUF implementations (NotaryV2 which was renamed to Notation). The newer signature specification should therefore be called Notation signature/signature spec.
To keep things simple and clearly delineated, I'd propose two set of tools/specifications under "Notary Project" GitHub organization.

1. Notary - the TUF based container image signing solution
2. Notation - the newer non-TUF based image signing solution

If we wish to retain notaryproject repo, I'd move all newer requirements and specs under a Notation subfolder.

[iamsamirzon]

LGTM but IAMNAM

[FeynmanZhou]

For the benefits of consumers: Create a FAQ on the documentation site that describe the above in user-friendly language (work item TBD)

@toddysm Do you mean to clarify terminologies like "Notary", "Notary V2", "Notary Project", "Notation" on the Notary Project documentation?

[toddysm]

What I mean is to create a FAQ that describes what is the difference between notary, TUF, Notary Project specification, and notation. What is what, what it means, how it works, and how it is different from the others? Hope this makes sense.

[priteshbandi]

LGTM

[yizha1]

Thanks for the votes. 6 out of 9 maintainers approved this proposal, we have reached a two-thirds supermajority. The next step is to fix the issues listed in the proposals. As discussed in 07/24 community call, the plan is to send out relevant PRs not later than Jul 27 PDT time, we will review the status in Jul 27 PDT community call. I will also take an action to update the existing governance guide to make it clear that super majority means a two-thirds supermajority.

[SteveLasker]

LGTM

[yizha1]

As follow-up on the proposal, here are the PRs and issues for review:

Issues and PRs to be completed before Notation v1.0.0 release:

.github repo: (governance and org maintainers)

• Proposal for renaming notaryproject\notaryproject to notaryproject\specifications #38
• Updated the README.md with overview details #32

notaryproject repo: (notaryproject maintainers)

• vote for notaryproject 1.0.0 release: Need to release 1.0.0 version of the notary project specification specifications#261
• doc: update signature specification for v1 release specifications#256
• doc: remove Notary v2 reference specifications#262
• doc: update readme.md for the Notary Project specifications#263

notation repo: (notation maintainers )

• doc: update README to align with the new brand name notation#750

Website: (website maintainers )

• Created glossary.md and defined project brand related terms notaryproject.dev#326

Issues and PRs NOT blocking Notation v1.0.0 release:

Repo Renaming (Requesting 2/3 supermajority of org and gov maintainers)

• Proposal for renaming notaryproject/notary repository to notaryproject/notary-tuf  #44

Updating Readme.md (requesting repo maintainers)

• docs: update README to align with the new project brand notation-go#343
• doc: update README to align with the new project brand notation-core-go#158
• Update readme to align with TUF notary#1685
• doc: update README to align with the new brand name notation-action#18
• Updated README file notaryproject.dev#295
• doc: update README to align with the new brand name notation-hashicorp-vault#9
• doc: update readme.md tuf#45
• doc: update readme.md meeting-notes#18
• doc: update readme.md roadmap#92

Archiving (Requesting 2/3 supermajority of org and gov maintainers)

• doc: Clarify the Repository lifecycle #37
• Archiving notaryproject/tuf repository #47 (Depending on Archiving process)

Website: (requesting repo maintainers)

• fixes #325 by updating references to The Notary Project notaryproject.dev#327

/cc: @toddysm @justincormack @gokarnm @priteshbandi @iamsamirzon @FeynmanZhou @SteveLasker @vaninrao10

[yizha1]

@iamsamirzon We didn't discuss your question during community meeting on Jul 31. I think we should use the Notary Project, not The Notary Project, except it is used at the beginning of a sentence. /cc @toddysm any comments?

[toddysm]

@yizha1 This was discussed in the meeting on 8/3 and the agreement is to use lowercase "the"

[yizha1]

Per the discussion in the meeting on 8/3, PR for adding glossary is not blocking for Notation CLI v1 release.

[yizha1]

We completed major work items per this proposal. However, there are still some work items to be closed. Most of them are related to update README.md for each repo. Here is the prioritized list for review:

README.md for notation-go and notation-core-go repo:

• docs: update README to align with the new project brand notation-go#343
• doc: update README to align with the new project brand notation-core-go#158

Archiving process:

• doc: Clarify the Repository lifecycle #37

README.md for other repos:

• doc: update readme.md tuf#45
• doc: update readme.md meeting-notes#18
• doc: update readme.md roadmap#92
• doc: update README to align with the new brand name notation-action#18
• Updated README file notaryproject.dev#295

[yizha1]

Closed this issue as most of the work items defined here are completed. The only work item left is tracked by this issue #47