Restructure purl-spec repository

[mjherzog]

Proposal: Restructure the purl-spec repository

Background

The purl-spec repository currently contains a few large rST files. The primary file is https://github.com/package-url/purl-spec/blob/main/PURL-SPECIFICATION.rst - it is essentially a narrative description of the PURL specification. We need to re-organize the repository files into a new structure that:

• Reflects the structure of the PURL Ecma Standard https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-purl-type-schema,
• Provides a home for the new JSON Schema files,
• Provides a home for the new PURL Type files (based on the JSON Schemas), and
• Adds standard policy files like CONTRIBUTING

NB: This proposal assumes that:

• We will create a new vers-spec repository with a similar overall structure.
• We will convert existing reStructuredText (.rst) file to Markdown (.md) format for ease of use in the GitHub context.
• purltype is a placeholder for PURL Type names.

Proposal

The following table shows the proposed repository layout.

Folder / File	Description	Included in Ecma standard
/.github/workflows		No
/docs/	New folder - does not include documentation generated for each PURL Type	No
/docs/annexes/	For future use - Colophon etc.	Yes
/docs/images/	For future use	Possible
/docs/build-purl.md	How to build a purl string from its components	No
/docs/purl-types.md	General information migrated from PURL-Types.rst	No
/docs/parse-purl.md	How to parse a purl string into its components	No
/docs/ecma/about.md	Content for the About the Specification section of the Ecma standard.	Yes
/docs/ecma/conformance.md	Text for the Ecma Conformance section	2 Conformance
/docs/ecma/introduction.md	Test for the Ecma Introduction section	Introduction
/docs/ecma/overview.md	Text for the Ecama PURL Overview section	4 Overview
/docs/ecma/purl-type.md	Introductory text for Section 6	6 PURL Type Schema
/docs/ecma/references.md	Text for the Ecma Normative Reference section	3 Normative References
/docs/ecma/specification.md	Content for section 5 of the Ecma standard: Package-URLSpecfication.	5.1 A PURL is a URL 5.2 Permitted characters 5.3 Separator characters 5.4 Character encoding 5.5 Component-level rules
/docs/tests.md	Introductory text for tests	No
/etc/scripts/		No
/schemas/	JSON Schema files	No
/schemas/purl-test.schema.json		7 PURL Test Schema
/schemas/purl-type-index.schema.json		6 PURL Type Schema
/schemas/purl-type.schema.json		6 PURL Type Schema
/tests/spec/specification-test.json		No
/tests/types/purltype-test.json		No
/types/	Contains one .json file for each registered PURL Type	Need to replace "known" with "registered" in many files
/types/docs/	Contains one .md file for each registered PURL Type	No
/types/docs/README.md	Auto-Generated PURLType Documentation	No
/types/docs/purltype-definition.md	Placeholder for markdown file generate for each registered PURL Type	No
/types/README.md	Canonical PURL Type Definitions	No
/types/purltype-definition.json	Placeholder for JSON file for each registered PURL Type	No
ADOPTERS.md	List of PURL Adopters - Need Issue/PR template for additions	No
CHANGELOG.md	Starting with purl-spec v0.90	No
CODE_OF_CONDUCT.md	rename code_of_conduct to upper case for consistency	No
CONTRIBUTING.md	New file	No
LICENSE.md	Need to clarify what our license fis for the overall specification	No
MAINTAINERS.md	New	No
README.md	Needs to be streamlined - primarily should have links to other documents.	No
purl-types-index.json	Generated index of registered PURL Types.	No

[stevespringett]

Generally, I think this makes sense. Few minor things:

• /docs/scope.md: may not need to exist. Its typically a one-liner and will always be confined to a single sentence - two at the max.
• /meetings/: I would highly suggest not including this in the purl-spec repo and creating a dedicated repo specific to meetings. When people want to work on a local fork of the purl-spec, we don't want their clone/checkout times to unnecessarily increase because they're downloading recordings.
• /tests/: this may not need to exist if each purl-type JSON definition contains the tests specific for that definition. Perhaps its only needed temporarily.

[mjherzog]

@stevespringett Thank you for the quick feedback. I applied the changes to the layout table (and learned how to do strikethrough in markdown).

[mjherzog]

@stevespringett I created a new Issue for the "meetings" repo: #523 . Your feedback would be appreciated.

[mjherzog]

Updated naming pattern for PURL Type files to purltype-definition.json and purltype-definition.md to make the content clear (maven.json or npm.json is somewhat ambiguous).
Added purltype-test.json under Description for /tests/.

[mjherzog]

@stevespringett - I have updated the proposed structure to match recent restructuring. I also added a new folder /docs/ecma/ to store documents that are directly related to the various sections of Ecma standard documentation versus more general specification documentation. Does this make sense to you?

[mjherzog]

@johnmhoran Please remove VERSION-RANGE-SPEC.rst from the purl-spec repo.

[johnmhoran]

@mjherzog For the record, your request lurking just above to remove VERSION-RANGE-SPEC.rst is moot because we changed our minds, right?