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