docs(registry): document how to add a package definition

[moshest]

Closes the gap behind #110.

The root README says "Anyone can contribute. If a library you use isn't listed, submit a PR to add it" and links to registry/. There is no registry/README.md and no CONTRIBUTING.md, so a contributor who follows that link finds six bare directories and no way to learn the conventions except by opening an issue — which is exactly what happened.

What it documents

Only things the code actually enforces, each verified against the CLI rather than read off the schema:

• The directory is the distributing registry, the filename is the package name. Scoped names use a subdirectory (npm/@trpc/server.yaml); Maven coordinates encode : as _.
• A project distributed by no package manager gets a directory named after itself holding one self-named file. This isn't a new convention — it's how python/python.yaml and java/java.yaml already work, which answers Documentation for Infrastructure Projects like Docker, Podman, Kubernetes #110 directly.
• The three source shapes, with a real example of each taken from existing definitions.
• How to build locally before opening a PR, and that a handful of sections usually means docs_path is wrong.

The trap worth writing down

versions: with min_version + a git source asks a version-discovery API "which versions exist?" before matching them. Only npm, pip, maven and hex have such an API. Anywhere else it throws, and since one bad definition fails the whole nightly publish, it takes every other package down with it — the exact failure mode that kept the nightly red for five nights in a row earlier this month.

Verified in a scratch registry:

registry/docker/docker.yaml, git + min_version   → Error: Unsupported registry: docker
registry/docker/docker.yaml, unversioned git     → docker/docker (1 versions): latest
registry/kubernetes/..., versioned zip           → kubernetes/kubernetes (2 versions): 1.31, 1.30

So the guide steers non-package-manager projects to unversioned or zip, and says why.

Docs-only; no changeset (nothing published changes).

---

Generated by Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 59b75c8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR