search

package-url / purl-spec

A minimal specification for purl aka. a package "mostly universal" URL, join the discussion at https://gitter.im/package-url/Lobby
https://github.com/package-url/purl-spec
Other
696 stars 161 forks source link

Move "how to" guides as appendices #334

Open adaaaam opened 3 weeks ago

adaaaam commented 3 weeks ago

To better clarify the specification, I suggest we move the How to build purl string from its components and How to parse a purl string in its components sections into appendices. These are important to support the PURL specification but not part of the specification and better organized as appendices to the specification.

adaaaam commented 3 weeks ago

Another step in this process is reviewing any rules in the "how to" guides and confirming that are included in the Rules for each purl component section.

matt-phylum commented 3 weeks ago

I think with the current state of the specification they are an integral part of the specification and removing them will lead to ambiguity, particularly with weird PURLs like pkg:npm/@angular/cli or pkg:generic/name@v/1. Maybe adding more tests to the test suite would be better than trying to make everyone manually review their implementations against the steps in the file (many implementations, including official implementations, do not do follow this procedure).

Other, better known specifications follow this same pattern of including a pseudocode implementation of the spec in the spec to ensure that implementations behave consistently for edge cases.

adaaaam commented 3 weeks ago

@matt-phylum agreed that they are important to include for clarifying the processes of building and parsing PURLs. this issue is suggesting moving them to the end of the specification to improve the readability of the spec itself.

we are planning work to add more tests to the test suite along with a PURL validation mechanism.