Why I kept an open-source maintenance evidence collector local-first

lee lee — Tue, 11 Aug 2026 05:36:27 +0000

Maintainers are often asked to explain whether a project is active, reproducible, and ready for outside contribution. The easy answer is to point at a dashboard or copy a few repository metrics. The harder question is: which signals can someone else reproduce, and what information should never leave the maintainer's machine?

I built a small Python CLI to explore that boundary:

https://github.com/5166li-beep/compassing-oss-maintainer-kit

The problem is not “more metrics”

For a small open-source project, a useful maintenance snapshot may include:

commits, active days, authors, and recent tags over a stated time window;
whether expected project documents exist, such as a README, license, contributing guide, security policy, and changelog;
whether the repository has workflow files and a test directory;
enough provenance that another person can understand when and how the snapshot was produced.

Those signals are incomplete. They do not prove quality, eligibility, popularity, or future maintenance. The tool therefore calls its output evidence, not a score.

Why local-first?

The collector reads a local Git checkout. By default it does not call GitHub, upload repository contents, or require an API token. This keeps the collection boundary easy to inspect and makes it usable for repositories whose history should not be sent to a third-party service.

The trade-off is intentional: a local report cannot claim public GitHub statistics unless those statistics are fetched separately and recorded with their source and timestamp. Mixing those two kinds of data would make the report look more complete while making it harder to audit.

A small privacy boundary

Git history can contain author names and commit subjects. The command supports author redaction, but redaction is not a magic privacy guarantee. Generated JSON and Markdown files still need a human review before they are shared.

python -m pip install .
maintainer-evidence --repo /path/to/your/repo --out evidence --redact-authors

The project currently targets Python 3.10+, has no runtime dependencies, and writes evidence/evidence.json plus evidence/evidence.md.

What this is not

It is not a hosted analytics dashboard, an eligibility checker, a GitHub permission verifier, or a replacement for project governance. It does not invent stars, downloads, users, or maintainer permissions. It is also not a claim that a report makes an application more likely to succeed.

What I need to learn

This is an early v0.1.0 / Alpha release. The repository has local tests and a read-only GitHub Actions workflow, but it has just been published and has no verifiable external users, external issues, or external pull requests yet.

The most useful feedback would be a reproducible run on a different Python 3.10+ environment or repository, especially if it exposes:

a misleading counting rule;
a missing maintenance signal;
a redaction edge case;
an installation or cross-platform problem.

Please use a GitHub Issue for a reproducible bug or design proposal:

https://github.com/5166li-beep/compassing-oss-maintainer-kit/issues