dgenio / dgenio/contextweaver

Add GOVERNANCE.md and a maintainer playbook (triage, release, escalation)

Open
#643 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

adoption complexity:complex contributor-experience documentation priority: medium
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

  1. GOVERNANCE.md: roles today, how decisions are made, how to become a triager/maintainer, conflict path; keep it short and true.
  2. 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; run make ci; tag; verify publish workflow; post-release fixture generation if the compat-suite candidate lands).
  3. 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.py etc.), 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.