Merge branch 'main' into 541-update-version-range-spec-rst

Author: mjherzog

PURL-TYPES.rst

@@ -62,8 +62,8 @@ repository with:
 
  - a new JSON definition file under `types/`.
  - a new JSON test file file under `tests/types/`.
- 
-  
+
+
 Ensure that your proposal follows the **PURL Type Definition Schema** and includes all required
 fields. For this see the README-dev.rst for details to run local checks.
 

README-dev.rst README-dev.mdREADME-dev.rst renamed to README-dev.md

@@ -1,33 +1,34 @@
-Development setup and instructions
-=====================================
+# Development setup and instructions
 
 We use some code:
 
 - to validate the JSON schemas for correctness and format them, and
 - to validate that the test suite data files are schema-valid.
 
 To setup an environment to contribute to the Package-URL spec and standard, follow these
-instructions::
+instructions:
 
-Setup
--------
+## Setup
 
 1. Ensure that you have a recent Python version 3 and Make installed.
-2. Configure your environment::
+2. Configure your environment:
 
+    ```bash
     make conf
+    ```
 
-Usage
--------
+## Usage
 
-To validate that the schemas and data files are correct, run::
-
-    make check
+To validate that the schemas and data files are correct, run:
 
+```bash
+make check
+```
 
 To regenerate the Python utility model code from the JSON schemas, then regenerate the
-PURL type documentation from the JSON PURL type definition files, run::
-
-    make generate
-    make docs
+PURL type documentation from the JSON PURL type definition files, run:
 
+```bash
+make generate
+make docs
+```

README.rst README.mdREADME.rst renamed to README.md

@@ -1,15 +1,12 @@
-Context
-=======
+# Context
 
 We build and release software by massively consuming and producing software
 packages such as NPMs, RPMs, Rubygems, etc.
 
 Each package manager, platform, type or ecosystem has its own conventions and
 protocols to identify, locate and provision software packages.
 
-
-Problem
-=======
+# Problem
 
 When tools, APIs and databases process or store multiple package types, it is
 difficult to reference the same software package across tools in a uniform way.
@@ -48,9 +45,7 @@ differences in syntax, naming and conventions:
 - Sonatype Lifecycle uses a format id followed by format specific coordinates.
   https://links.sonatype.com/products/nxiq/doc/component-identifier
 
-
-Solution
-========
+# Solution
 
 A `purl` or package URL is an attempt to standardize existing approaches to
 reliably identify and locate software packages.
@@ -62,17 +57,14 @@ packaging conventions, tools, APIs and databases.
 Such a package URL is useful to reliably reference the same software package
 using a simple and expressive syntax and conventions based on familiar URLs.
 
-
 Check also this short `purl` presentation (with video) at FOSDEM 2018
 https://fosdem.org/2018/schedule/event/purl/ for an overview.
 
-
-purl
-~~~~~
+## purl
 
 `purl` stands for **package URL**.
 
-A `purl` is a URL composed of seven components::
+A `purl` is a URL composed of seven components:
 
     scheme:type/namespace/name@version?qualifiers#subpath
 
@@ -94,20 +86,14 @@ The definition for each components is:
 - **subpath**: extra subpath within a package, relative to the package root.
   Optional.
 
-
 Components are designed such that they form a hierarchy from the most significant component
 on the left to the least significant component on the right.
 
-
 A `purl` must NOT contain a URL Authority i.e. there is no support for
 `username`, `password`, `host` and `port` components. A `namespace` segment may
 sometimes look like a `host` but its interpretation is specific to a `type`.
 
-
-Some `purl` examples
-~~~~~~~~~~~~~~~~~~~~
-
-::
+## Some `purl` examples
 
     pkg:bitbucket/birkenfeld/pygments-main@244fd47e07d1014f0aed9c
 
@@ -138,23 +124,19 @@ Some `purl` examples
 
 (NB: some checksums are truncated for brevity)
 
-
-Specification details
-~~~~~~~~~~~~~~~~~~~~~
+## Specification details
 
 The `purl` specification consists of a core syntax definition and independent
 type definitions:
 
 - `Package URL core <PURL-SPECIFICATION.rst>`_: Defines a versioned and
   formalized format, syntax, and rules used to represent and validate `purl`.
 
-- `Type definitions <PURL-TYPES.rst>`_: Defines `purl` types (e.g. maven, npm,
+- `Type definitions <PURL-TYPES.md>`_: Defines `purl` types (e.g. maven, npm,
   cargo, rpm, etc) independent of the core specification. Definitions also
   include types reserved for future use.
 
-
-Known implementations
-~~~~~~~~~~~~~~~~~~~~~
+## Known implementations
 
 - .NET: https://github.com/package-url/packageurl-dotnet
 - Erlang / Elixir: https://github.com/erlef/purl
@@ -170,14 +152,6 @@ Known implementations
 - Rust: https://github.com/package-url/packageurl.rs
 - Swift: https://github.com/package-url/packageurl-swift
 
-
-Users, adopters and links
-~~~~~~~~~~~~~~~~~~~~~~~~~
+## Users, adopters and links
 
 See the `dedicated adopters list <ADOPTERS.md>`_.
-
-
-License
-~~~~~~~
-
-This document is licensed under the MIT license

docs/candidate-purl-types.md

@@ -0,0 +1,48 @@
+## Other candidate types to define
+
+- ``android`` for Android apk packages
+- ``apache`` for Apache projects packages
+- ``atom`` for Atom packages
+- ``bower`` for Bower JavaScript packages
+- ``brew`` for Homebrew packages
+- ``buildroot`` for Buildroot packages
+- ``carthage`` for Cocoapods Cocoa packages
+- ``chef`` for Chef packages
+- ``chocolatey`` for Chocolatey packages
+- ``clojars`` for Clojure packages
+- ``coreos`` for CoreOS packages
+- ``crystal`` for Crystal Shards packages
+- ``ctan`` for CTAN TeX packages
+- ``drupal`` for Drupal packages
+- ``dtype`` for DefinitelyTyped TypeScript type definitions
+- ``dub`` for D packages
+- ``ebuild`` for Gentoo Linux portage packages
+- ``eclipse`` for Eclipse projects packages
+- ``elm`` for Elm packages
+- ``gitea`` for Gitea-based packages
+- ``gitlab`` for GitLab-based packages
+- ``gradle`` for Gradle plugins
+- ``guix`` for Guix packages
+- ``haxe`` for Haxe packages
+- ``helm`` for Kubernetes packages
+- ``julia`` for Julia packages
+- ``melpa`` for Emacs packages
+- ``meteor`` for Meteor JavaScript packages
+- ``nim`` for Nim packages
+- ``nix`` for Nixos packages
+- ``opam`` for OCaml packages
+- ``openwrt`` for OpenWRT packages
+- ``osgi`` for OSGi bundle packages
+- ``p2`` for Eclipse p2 packages
+- ``pear`` for Pear PHP packages
+- ``pecl`` for PECL PHP packages
+- ``perl6`` for Perl 6 module packages
+- ``platformio`` for PlatformIO packages
+- ``puppet`` for Puppet Forge packages
+- ``sourceforge`` for Sourceforge-based packages
+- ``sublime`` for Sublime packages
+- ``terraform`` for Terraform modules
+- ``vagrant`` for Vagrant boxes
+- ``vim`` for Vim scripts packages
+- ``wordpress`` for Wordpress packages
+- ``yocto`` for Yocto recipe packages

docs/maintain-purl-types.md

@@ -0,0 +1,30 @@
+## How PURL Types are maintained
+
+PURL type definitions are maintained as JSON definition files and JSON
+test files in the PURL specification repository. These JSON files serve as
+the source of truth and define the structure of each PURL type, including:
+
+- Namespace and name formatting rules
+- Supported qualifiers
+- Repository requirements
+- Mapping of PURL concepts to the native ecosystem concepts
+
+On commit, a job automatically:
+
+- Checks that all JSON files are schema-valid
+- Formats all the JSON files
+- Generates the ``purl-types-index.json`` file containing a list of defined
+  registered PURL types
+- Generates human-readable documentation for each type
+
+## How to Propose a New PURL Type
+
+To propose a new PURL type, create an **issue** and a corresponding
+**pull request** in the repository with:
+
+- a new JSON definition file under `types/`.
+- a new JSON test file file under `tests/types/`.
+
+Ensure that your proposal follows the **PURL Type Definition Schema** and
+includes all required fields. For this see the README-dev.md for details to
+run local checks.

docs/standard/about.md

@@ -19,5 +19,5 @@ This specification is developed on GitHub with the help of the Package-URL commu
 * Community:
   * Chat: [Slack Channel](https://cyclonedx.slack.com/archives/C06KTE3BWEB)
 
-Refer to the [colophon](https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-colophon) for more information on how this document is created.
+Refer to the [colophon](https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-colophon) for more information on how this document was created.