Skip to content

Standardize the per-enricher docs chapter template #28

@Metbcy

Description

@Metbcy

Context

The per-enricher docs (docs/src/enrichers/{typosquat,osv-cve,version-jump,maintainer-age,epss,kev,registry}.md) grew organically across v0.5–v0.9.7. v0.9.6's docs refresh standardized some of them around the sections Why this signal / Algorithm / Threshold / Output / Network / Disabling / Calibration / See also, but the coverage is still uneven.

Scope

Audit each enricher chapter and bring them all to the same shape:

  • docs/src/enrichers/typosquat.md
  • docs/src/enrichers/osv-cve.md
  • docs/src/enrichers/version-jump.md
  • docs/src/enrichers/maintainer-age.md
  • docs/src/enrichers/epss.md
  • docs/src/enrichers/kev.md
  • docs/src/enrichers/registry.md

Sections (in this order):

  1. Why this signal — what supply-chain risk does it catch?
  2. Algorithm — high-level shape (links to source for detail).
  3. Threshold — what number(s) drive the gate; defaults; why those.
  4. Output — what the markdown/term/JSON/SARIF/VEX output looks like.
  5. Network — does it touch the network? Cache TTL? Best-effort fallback?
  6. Disabling--no-<name> flag + config key.
  7. Calibration — relevant CLI/config knobs (--typosquat-similarity-threshold, etc.).
  8. See also — cross-links to relevant subjects (license-policy.md, sarif.md, etc.).

Acceptance criteria

  • Each of the 7 enricher chapters has all 8 sections (or a brief explanation if a section is N/A — e.g. version-jump has no network).
  • Section ordering identical across chapters.
  • Cross-links resolve.
  • docs/src/enrichers/overview.md table summary still matches.

No code changes; pure docs work.

A note on commit signing

main requires verified signatures (the repo ships cosign-signed releases — we hold our own commits to the same bar).

You usually don't need to set up signing as a contributor — when a maintainer merges via "Merge" or "Squash", GitHub auto-signs the resulting commit and your unsigned PR-branch commits are fine. The friendlier path for everyone.

If you'd like your individual commits to land verbatim on main (so your name shows up in git blame), set up local signing once and your PR can be rebase-merged:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Then add the same SSH public key under GitHub → Settings → SSH and GPG keys → Signing keys.

See CONTRIBUTING.md → Commit signing on main for the full picture. Either way, please don't sweat it — if your PR is otherwise great, the maintainer will pick a merge mode that works.

Metadata

Metadata

Assignees

No one assigned

    Labels

    adoptionWork that helps first-time users adopt bomdriftdocumentationImprovements or additions to documentationgood first issueGood for newcomers

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions