Skip to content

Bus factor: co-maintainer onboarding + handoff docs #159

Description

@whisper67265

Problem

The project relied on a single maintainer and scattered tribal knowledge in the README. There was no formal co-maintainer roster, escalation path, structured issue intake, or consolidated documentation of non-obvious Weblate integration points—raising bus-factor risk and slowing onboarding for new contributors or maintainers.

Acceptance Criteria

  • MAINTAINERS.md lists Andrew Zhang and William Jin as co-maintainers with equal rights, plus a documented escalation path when maintainers are unresponsive
  • CONTRIBUTING.md covers the full local dev loop: uv install, prek hooks, pytest (including coverage gate), Docker plugin tests, and Weblate version pin workflow
  • docs/maintainer-handoff.md documents Weblate coupling points (settings exec(), FormatsConf AST parsing, URL registration, version pins) and includes a first verified change walkthrough
  • GitHub issue templates (bug report, feature request), blank-issue disablement, and CODEOWNERS route review to both co-maintainers

Implementation Notes

  • Contributing guidance was extracted from README.md into CONTRIBUTING.md; the README now links to governance docs and provides a quick reference only
  • docs/maintainer-handoff.md deliberately avoids duplicating existing API/deployment docs and instead indexes them while explaining why each Weblate coupling exists
  • pyproject.toml source-include was updated so CONTRIBUTING.md and MAINTAINERS.md ship with the package

References

  • .github/CODEOWNERS
  • .github/ISSUE_TEMPLATE/bug_report.yml
  • .github/ISSUE_TEMPLATE/config.yml
  • .github/ISSUE_TEMPLATE/feature_request.yml
  • CONTRIBUTING.md
  • MAINTAINERS.md
  • docs/maintainer-handoff.md
  • README.md
  • pyproject.toml

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions