Maintainer Ready

Maintainer Ready is a small command-line tool that audits whether an open-source repository has the public signals maintainers usually need before a project can grow: a useful README, a license, contribution guidance, security policy, issue templates, pull request template, tests, CI, changelog, and release evidence.

It is built for solo maintainers and small teams who want a practical checklist, not a heavy governance framework.

Why this exists

Many promising open-source projects fail to look trustworthy because the basics are scattered or missing. Maintainer Ready gives maintainers a repeatable report they can run before a release, before asking for contributors, or before sharing the project publicly.

Install

python -m pip install maintainer-ready

For local development:

python -m pip install -e .

Usage

Audit the current repository:

maintainer-ready .

Write machine-readable output:

maintainer-ready . --json

Fail when the score is below a threshold:

maintainer-ready . --min-score 80

Example Output

Maintainer Ready report for .
Score: 86/100

PASS  README                 README.md has substantial project context
PASS  License                LICENSE found
PASS  Contribution guide     CONTRIBUTING.md found
WARN  Security policy        SECURITY.md is missing
PASS  Issue templates        GitHub issue templates found
PASS  Pull request template  Pull request template found
PASS  Tests                  Test directory found
PASS  CI                     GitHub Actions workflow found
PASS  Changelog              CHANGELOG.md found
WARN  Release evidence       No local git tag or release note heading found

What It Checks

Maintainer Ready looks for public, verifiable signals:

• project purpose and usage documentation
• open-source license
• contribution process
• security reporting path
• issue and pull request templates
• tests and CI
• changelog or release notes
• local release evidence such as git tags or version headings

These checks are intentionally simple. They are meant to make a repository easier for humans to trust and contribute to.

Roadmap

• GitHub API mode for stars, forks, open issues, merged pull requests, and release activity
• optional PyPI and npm download checks
• Markdown report output for posting in issues
• repository badge generation
• sample GitHub Action that comments readiness reports on pull requests

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or pull request.

License

MIT