Proposal for renaming notaryproject\notaryproject to notaryproject\specifications

[toddysm]

As part of the discussions we are having about cleaning up the branding (#32 and #35) there is a proposal to archive the notaryproject repository as it is confusing and replace it with a new repository. This issue is intended to describe the proposal for the new repository, its purpose and structure.

The proposal is to create a new repository with the name specifications that will contain specifications shared across "subprojects" under Notary Project as well as used by other OSS projects and/or vendor tools that want to interoperate with Notary Project tooling. Here the details:

• Repository name: specifications
• Repository purpose: Cross tooling and interoperability specifications
• Structure:
  • specifications repository
    • oci-signature-specification folder
      Those specifications are OCI specific and describe how the Notary Project Signing Scheme is applied to signatures stored in OCI registries. The folder contains the following documents:
      • Signature Specification referred to as "Notary Project OCI Signature Specification" or just "OCI Signature Specification" if the Notary Project reference is implied.
      • Signing and Verification Workflow referred to as "Notary Project OCI Signing and Verification Workflow" or just "OCI Signing and Verification Workflow" if the Notary Project reference is implied.
      • Signing Envelope COSE referred to as "Notary Project OCI COSE Envelope" or just "OCI COSE Envelope" if the Notary Project reference is implied. Ideally, we would like to have COSE envelope spec that is not specific to OCI.
      • Signing Envelope JWS referred to as "Notary Project OCI JWS Envelope" or just "OCI JWS Envelope" if the Notary Project reference is implied. Ideally, we would like to have JWS envelope spec that is not specific to OCI.
    • signing-scheme folder
      This specification is not specific to any storage and describes the supported signing schemes. Ideally any tool that supports those schemes should be able to produce signatures that are understood by Notary Project tools. Ideally, we would like to have non-OCI specific envelope specifications in this folder also. This folder contains the following documents:
      • Signing Scheme referred to as "Notary Project Signing Scheme" or just "Signing Scheme" if the Notary Project reference is implied.

In the future, this repository may contain specifications about identities, attestations, counter receipts, etc. depending on how the Notary Project evolves.

[sajayantony]

Adding @gokarnm in this conversation since the comment - notaryproject/notary#1685 (comment) is related to this proposal.

[FeynmanZhou]

I think the term "OCI" has been implied in the folder name so it's not necessary to replicate "OCI" in each individual file name.

Considering the user's search habits and SEO, I would suggest including "Notary Project" in each individual file name (URL) and also the document title. Using a too simple and generic title is not beneficial for SEO. My proposed structure are as follows

• Folder: oci-signature-specification
  • File: Signature Specification --> "Notary Project Signature Specification"
  • File: Signing and Verification Workflow --> "Notary Project Signing and Verification Workflow"
  • File: Signing Envelope COSE --> "Notary Project COSE Envelope"
  • File: Signing Envelope JWS --> "Notary Project JWS Envelope"
• Folder: Notary Project Signing Scheme

[toddysm]

@FeynmanZhou those specifications may be referred from specifications, blog posts, articles and other documents that are not in that folder and without the context of the folder name. That is why it is important to define a clear name for them to avoid ambuiguity.

[iamsamirzon]

@toddysm - Is there a proposal for the other two specifications currently present in the https://github.com/notaryproject/notaryproject/tree/main/specs - The plugin-extensibility.md and trust-store-trust-policy.md ?

Also, what about the other sub folders in the notaryproject repo - Security, Requirements, media

[toddysm]

@iamsamirzon thanks for asking.

• plugin and trust store are very specific to Notation, so those should be specs under Notation IMHO
• regarding the security audits, we should have those in the .github repo if they are across subprojects or in the specific repos if they are specific to a subproject

[sajayantony]

I believe this issues needs to be retitled as renmae notaryproject\notaryproject to notaryproject\specficiation
Just to confirm is it specification or specfications? Should the repository be specification and not plural similar to image-spec/distribution-spec tuf spec etc.

[yizha1]

We may need to separate the signature storage from signature specification and write a new specification for signature storage, since the signature can be stored in OCI compliant registries or in a filesystem as a file, see notaryproject/notation#741

[yizha1]

I believe this issues needs to be retitled as renmae notaryproject\notaryproject to notaryproject\specficiation Just to confirm is it specification or specfications? Should the repository be specification and not plural similar to image-spec/distribution-spec tuf spec etc.

Just a question: Based on proposal #35 , folder "requirements" will not be maintained any more. So, if we don't archive repo notaryproject and just rename it, is there a way to mark one folder under this repo not in active maintenance?

[yizha1]

As one work item from the approved proposal #35 (comment) and alignment in community meeting on Jul 24 PDT, this proposal requires a two-thirds supermajority of the maintainer votes, please reply LGTM to this proposal. As the one writing this proposal, my vote is LGTM.

@SteveLasker @justincormack @NiazFK @gokarnm @toddysm @FeynmanZhou @vaninrao10 @priteshbandi @iamsamirzon

[SteveLasker]

Just a question: Based on proposal #35 , folder "requirements" will not be maintained any more.

I'd agree with @TheFoxAtWork for this comment:

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.

Keeping the requirements and scenarios as a single doc, provides context to the purpose of the project and it's goals. Which should continue to evolve. Converting these to issues or archiving would lose that context in a meaningful way.

[yizha1]

Thanks @SteveLasker .

I will create a separate issue for addressing the folder structure. This issue will be used for Proposal for renaming notaryproject\notaryproject to notaryproject\specifications

[yizha1]

@SteveLasker @justincormack @NiazFK @gokarnm @toddysm @FeynmanZhou @vaninrao10 @priteshbandi @iamsamirzon

Please reply LGTM to if you agree on renaming notaryproject\notaryproject to notaryproject\specifications
As the one writing this vote, my response is LGTM.

Regarding to folder structure discussion, please go to this issue #48

[toddysm]

I created the proposal, so my +1 should be implicit 😀

[yizha1]

LGTM

[FeynmanZhou]

LGTM

[iamsamirzon]

LGTM for renaming notaryproject\notaryproject to notaryproject\specifications

[gokarnm]

LGTM, except for Trust Store and Trust Policy should be part of the Notary Project specifications, it has the core verification logic that is references from the OCI specific steps in Signing and Verification Workflow.

[priteshbandi]

LGTM for renaming of repo, we will have separate issue for restructure of package content.

[justincormack]

LGTM

[yizha1]

Thank you all for voting. We have received 6 LGTMs out of 9 MAINTAINERS, thus reached two-third supermajority to approve renaming from notaryproject/notaryproject to notaryproject/specifications.

[yizha1]

The renaming and purpose of repository were updated, see https://github.com/notaryproject/specifications

@toddysm Maybe we can close this issue and refer to #48 for folder structure and content discussion.

[yizha1]

Close as the renaming was completed. Please go to #48 for folder structure and content discussion.