Add GOVERNANCE.md and a maintainer playbook (triage, release, escalation)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 9
- Forks
- 17
- Avg merge
- 21h 36m
- Merged PRs (30d)
- 22
Description
Summary
Document how the project is governed and operated: decision-making (currently single-maintainer — say so plainly), the path to additional maintainers/triagers, triage expectations for issues/PRs/Discussions, the release procedure as a checklist (tag → publish workflow → CHANGELOG/CITATION/announcement steps), and security-escalation handling.
Why this matters
Teams evaluating a pre-1.0 infrastructure dependency weigh bus factor and process as much as code. The repo's engineering process is exceptionally documented for agents (AGENTS.md, workflows.md) but project governance for humans is absent — making explicit what already happens (and the on-ramp to co-maintainership) lowers adoption risk and invites sustained contributors rather than drive-bys.
Current evidence
- No GOVERNANCE.md / MAINTAINERS file (file listing verified);
CODE_OF_CONDUCT.md,CONTRIBUTING.md, SECURITY.md exist. - Release mechanics are encoded in
.github/workflows/publish.yml+ drift gates but the human checklist isn't written anywhere visible (CITATION.cff staleness was a past launch bug, closed #254 — process gap evidence). - Open #446 (contributor on-ramp) covers task content, not governance; no overlap found.
External context
GitHub community standards and OpenSSF best-practices badge criteria both include governance documentation; single-maintainer projects benefit most from honest role/expectation statements.
Proposed implementation
GOVERNANCE.md: roles today, how decisions are made, how to become a triager/maintainer, conflict path; keep it short and true.docs/maintainers.md(or RELEASING.md): step-by-step release checklist derived from the workflows and drift gates (version bump points:pyproject.toml, README references, CITATION.cff; runmake ci; tag; verify publish workflow; post-release fixture generation if the compat-suite candidate lands).- Triage SLA statement aligned with SECURITY.md's existing response table (don't promise more than the maintainer will keep).
AI-agent execution notes
- Inspect first:
publish.yml, drift-gate scripts (check_readme_version.pyetc.),CITATION.cff, closed launch issues #237/#253/#254 for historical release pitfalls to encode. - Tone: factual, modest commitments; this is a maintainer-approval-heavy doc — draft for review, don't invent policy.
Acceptance criteria
- GOVERNANCE.md merged stating current model and contributor advancement path.
- Release checklist documents every version-bearing file and gating check; dry-run validated against the v0.14.0 release facts.
- Linked from README community section and CONTRIBUTING.
Test plan
make docs and link checks; checklist dry-run review.
Documentation plan
The documents are the deliverable; CHANGELOG note.
Migration and compatibility notes
Not expected to require migration.
Risks and tradeoffs
Stated SLAs create expectations — keep ranges honest; minor upkeep at each process change.
Suggested labels
contributor-experience, documentation, adoption
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading .github/workflows/publish.yml, the drift-gate scripts such as check_readme_version.py, CITATION.cff, SECURITY.md, and the referenced launch issues. Run make docs and link checks, then dry-run the release checklist against the v0.14.0 facts; done means GOVERNANCE.md and the maintainer release document are reviewed, complete, and linked from README and CONTRIBUTING.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, python
- Domain
- developer-experience, documentation, release
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100