Skip to content

shrink the README to one screen, document providers and versions - #210

Open
adssib wants to merge 2 commits into
pl-r4-versionsfrom
pl-r5-readme
Open

adssib wants to merge 2 commits into
pl-r4-versionsfrom
pl-r5-readme

Conversation

@adssib

@adssib adssib commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #209. Refs #178 (I19.7, the "which kind" part of writing-a-plugin.md) and #171.

What this changes

Docs only.

  • README.md is one screen (37 lines): what the repo is in two lines, badges (no counts), "Add a provider in 15 minutes" in three steps, and links to docs/, CONTRIBUTING, AGENTS, Discussions and the docs site. No coverage table, no provider names list, no layer statuses.
  • docs/how-it-works.md (new): providers, sources, kinds and layers; what a plugin does, version by version; the layout; the checks; releases (with the plugins.json asset). This is what used to be in the README's lower half, updated.
  • docs/writing-a-plugin.md: providers, sources (provider/source), kinds ("Pick the kind", with the no-Kubernetes-kind rule), layers; registering with plugin.RegisterProvider; a new section "Every version, not only the newest" (ListVersions, ReadAt, Extract, core/versions, never pin a tag in code: pin a case in the test); core/github for GitHub lookups.
  • docs/README-template.md: the README shape every public repo follows is now one screen (what, badges, three-step quickstart, links) and never lists what's covered (the old "What it covers" table with Noticed/Fixed statuses is gone from the template).

Checklist

  • Metadata: not applicable, no source changes
  • Every commit is signed off (DCO)
  • Golden tests: every golden byte-identical (no code change)
  • testdata/README.md, drop tests, provider pages: not applicable
  • Fetches: not applicable
  • make check passes locally
  • Nothing private

Calls I made (please check)

  • The README drops the "Why" paragraph, the mermaid diagram and the "What patch-it does" story (including the "8 pull requests merged" proof line): the agreed one-screen shape is "what in two lines, three-step start, links". The story lives on patch-it.dev and the docs site; the README links both. Say if you want the diagram back.
  • The template change applies to every public patch-it repo's README; their own READMEs aren't changed here.

Related PRs

🤖 Generated with Claude Code

The README says what the repo is in two lines, adds a provider in three
steps and links docs/. How a plugin works, the layout, the checks and
releases move to docs/how-it-works.md. writing-a-plugin.md covers providers,
sources, kinds and layers, registering with RegisterProvider, and reading a
source version by version (ListVersions, ReadAt, Extract, core/versions).
The README template is one screen too, and never lists what's covered.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant