project quality

Repository health checklist

A healthy repository helps people understand what a project is, whether it is active, how to contribute and where to look for evidence. This checklist is a practical starting point for any open-source project.

checklist

What a useful repository should make clear

First impression

  • The README explains what the project does and who it is for.
  • The current status is clear: experimental, testnet, production, maintenance mode or archived.
  • The license is visible and appropriate for open-source reuse.
  • The main repository, docs and release locations are easy to find.

Contributor path

  • CONTRIBUTING.md explains how to build, test and submit changes.
  • Issues or discussions show where newcomers can ask questions.
  • Useful first issues, labels or project boards make current work discoverable.
  • Expected review behavior and response times are stated or easy to infer.

Maintenance signals

  • Maintainers and areas of responsibility are named.
  • Recent commits, releases, issues or reports show whether the project is active.
  • Roadmap or milestone information is public enough for users to understand direction.
  • Known limitations and risks are documented honestly.

Security and operations

  • SECURITY.md or equivalent explains how to report vulnerabilities.
  • CI, tests or reproducible checks are visible to reviewers.
  • Release artifacts, packages or deployment instructions can be verified.
  • Critical credentials, package ownership and domain ownership have more than one responsible person.

Community evidence

  • Usage, integrations, examples or demos are linked where available.
  • Funding, grants or treasury work are disclosed when relevant.
  • Major decisions, incidents or scope changes have public notes.
  • Quarterly reports or progress updates exist when the project has public commitments.
how to use

Use it as a review aid, not a gate

Repository health is not a single score. Young projects, research prototypes and mature infrastructure projects will look different. The useful question is whether a reasonable reviewer, contributor or user can understand the project without private context.

Projects can use this checklist before applying to PRAGMA, before asking for public funding, before onboarding new maintainers, or as a periodic self-review. The gaps it surfaces are often good candidates for small documentation and governance improvements.

resources

Related resources

CNCF project templates

Reference examples for README, governance, maintainers, reviewing, security and contributor documents.

OpenSSF Scorecard

Automated checks that help identify common security and supply-chain health signals in open-source repositories.

CHAOSS metrics

Community health metrics and models for thinking about project activity, responsiveness and sustainability.

PRAGMA project intake and maturity checklist

A broader self-assessment for projects preparing for PRAGMA review or continuing to mature in public.