Registry Spec

[thomashoneyman]

This issue tracks writing the registry spec across a complete table of contents. Current progress:

• Abstract
  The untitled first 1-2 paragraphs, which explain what the registry is and what major concepts the spec will cover.
• 1. Introduction
  A longer summary of the registry, why it came to exist, its high-level design. Akin to the introduction to a book (in spirit, not in length!).
• 2. Package Publishing
  A simple walkthrough of how a package is published, possibly including diagrams. Includes example JSON payloads going through the registry Addition operation, an example of the input manifest, the output metadata and package sets entry. All extremely minimal, but giving a sense of the data interchange beginning with the package manager and ending with the registry metadata, index, and storage backend.
• 3. Schemas: Data Type Representations Used in the Registry
  Types alone can't capture the set of invariants applied to data processed by the registry, so this section provides the full set of rules for common data types.
• 4. Registry Infrastructure
  A section specifying how the registry should relate to other infrastructure and the responsibility of that infrastructure as it relates to the registry.
• 5. Registry Operations
  The big section! This builds on everything provided so far and summarizes the role of the API and its major operations. Each operation is detailed along with its failure modes.
• 6. Post-Publishing Operations
  Summarizes what operations the registry will take after a package is added / published, transferred, or unpublished. This section could be folded back into the previous section, but I worry that doing so would make that section too long and unfocused.
• 7. Non-JavaScript Backends
  A section summarizing the aliasing solution used to support alternate backends, along with a status note stating that this is currently un-implemented.
• 8. Package Managers
  Specifies how package managers should relate to the registry, ie. open a GitHub issue with a payload according to the Operation data type, get package information from registry-index, download packages from the storage backend, etc.
• 9. Policies
  Policies followed by the registry (trustees, name squatting, package sets)

---

Note that this spec is just one of several documents we should provide to registry users, including:

1. The registry spec, located in registry-dev, intended for registry developers & related development (package managers, package sets consumers, etc.)
2. The registry user guide, located in registry, intended for package authors who want to know the broad concepts of the registry and package sets (though they should largely defer to their package manager)
3. Various policies, such as the registry trustees policy and legal policies like DMCA takedown notices, located in registry
4. The trustees document listing out the Registry trustees, located in purescript/governance and managed by the core team
5. A roadmap document, located in registry-dev, which lists out items that are in the spec but not yet implemented

This issue only concerns the registry spec. It doesn't include information better located in other documents (e.g. a step-by-step guide to publishing packages).

Second, this is a draft table of contents only. I'd like to get to consensus on what the spec should include and then tackle it section-by-section. Once there's consensus this issue can become a tracking issue.

[JordanMartinez]

LGTM! 😄 Not sure how much value that itself is, but the overall direction makes sense.

[f-f]

This all looks great! 👏