​

Maintainer’s handbook

​

1. The triage loop

​

Cadence

​

The Triage view

​

For each issue

1. Read it. If it’s a duplicate or wontfix → label and close with a kind message.
2. Under-specified? Add needs-info, ask the question, await reply. Set a calendar reminder to follow up if the reporter goes silent for 14 days.
3. Otherwise, apply labels:
   • Exactly one type:* (type:bug, type:enhancement, …).
   • Exactly one area:*.
   • One priority:* and one effort:*.
   • Pathway decision (see §2 below).
   • good first issue if a newcomer can finish it in under 2 hours without reading internal docs.
4. Add to a milestone if the issue is on the near-term roadmap.
5. Remove needs-triage.

​

Pathway decision

• Size and layer span.
• DB schema changes or migrations.
• New runtime dependencies.
• Public-API contract changes.
• Whether an architectural decision is involved (an ADR may be warranted).

​

2. Labels: what each one means

• Every issue gets exactly one type: label.
• Every issue gets exactly one area: label. (Labeler workflow auto-applies the area on PRs from changed paths.)
• needs-triage must be removed once triage is done. This is the signal to the rest of the world that the issue is actionable.
• good first issue is sacred. Reserve it for issues a newcomer can finish in under 2 hours without reading internal docs. Putting it on harder issues kills trust faster than anything else.
• path:ai-automation (or an engine-specific path:ai-automation-{claude,codex,copilot}) is added explicitly by you, or automatically when you assign HAI-Coco to the issue. Default is traditional (absence of any path:* label means traditional). The bare label is the Copilot alias (default engine; requires a seat).
• stage:* labels are managed automatically by coco-stage-labels.yml; never set them by hand. Each AI-pathway issue and PR shows its lifecycle stage (stage:planning … stage:awaiting-merge) in the Issues and Pull-requests lists, so you can see where everything is at a glance; warm colors mean it is your turn to act. See the state diagram in ai-pathway.md.

​

3. Reviewing PRs

​

The same bar for both pathways

​

What to check

• Target branch is develop. PRs to main are release promotions only.
• PR title is Conventional Commits. Reject anything else, since the title becomes the squash-commit message and the Release Drafter category.
• Closes #... in the body. Without this, the issue does not auto-close.
• CI is green. Lint, tests, build.
• CODEOWNERS approval. You are usually the CODEOWNER; review accordingly.
• No secrets committed. Push protection catches the obvious ones; you catch the rest.
• ADR for architectural changes. If the diff changes how modules compose, how data flows, or which framework owns what, ask for an ADR in the same PR. See docs/adr/README.md.

​

Responding to Coco

/coco the dev container fails health-check at /api/health.
The cause looks like a missing env var. Please add a default to settings.py
and a test that covers the missing-env path.

​

Merging

• Squash merge. Always. The PR title becomes the commit; the body appears below.
• The branch auto-deletes.
• The linked issue auto-closes on merge into develop.

​

4. Releases

​

Two channels, one CI workflow

​

Cutting a dev release

1. The dev draft release accumulates as PRs merge to develop. Review the draft at Releases → Draft (dev) for any title cleanups.
2. From develop, push the next dev tag:
   git checkout develop
   git pull
   git tag dev-v0.3.1
   git push origin dev-v0.3.1
   
3. Publish the draft release (its tag-template matches your pushed tag).
4. ci.yml builds and pushes the :dev + :X.Y.Z images and runs the dev deploy job.

​

Cutting a production release

1. The prod draft release accumulates as develop is fast-forwarded into main. Review it.
2. Promote develop → main:
   git checkout main
   git merge --ff-only develop       # locally; or via a PR develop → main
   git push origin main
   git tag v1.0.0
   git push origin v1.0.0
   
3. Publish the prod draft release.
4. ci.yml builds and pushes the :latest + :X.Y.Z images and runs the prod deploy job.
5. Open a 📣 Announcement discussion linking the release page, highlighting notable PRs/Issues. The Announcement is the highest-leverage outreach mechanism short of social posts.

​

Why two Drafters

​

5. ADRs: the bright line

• The decision shapes the structure of more than one module or service.
• The decision picks one of several reasonable approaches, and a future contributor would reasonably ask “why this?”.
• The decision constrains future work (framework, database, wire format, topology).
• The decision touches the dual-pathway model, the release workflow, or any governance question.

​

6. Reading the Project board

​

7. The community standards page

• Description.
• README.
• Code of Conduct.
• Contributing.
• License.
• Security policy.
• Issue templates.
• PR template.

​

8. Recurring chores

• Dependabot: opens grouped PRs weekly for pip, npm, docker, and github-actions. Treat them as ordinary PRs; squash-merge after green CI.
• Release Drafter (dev/prod): runs on every merge; keep an eye on the draft, fix titles before publishing.
• Labeler: runs on every PR open; auto-applies area:*.
• Stale bot: Monday 06:00 UTC weekly; conservative (180-day idle, 21-day warning). Watch the first run after enabling and confirm nothing important was swept.
• CodeQL + Autofix: runs on PRs; surface findings in Security tab.

• Weekly triage (§1).
• Monthly: glance at the Discussions tab for unanswered Q&A.
• Quarterly: re-read docs/repository-foundation.md and tune the issue forms based on which fields contributors skip.
• On release: cut tags, publish drafts, open the Announcement.

​

9. Sources and related docs

• docs/repository-foundation.md: the long-form setup guide; rationale for every convention here.
• docs/community-guide.md: the contributor-facing view of the same conventions.
• docs/labels-reference.md: full taxonomy.
• docs/adr/README.md: how ADRs work.
• docs/going-public.md: public-launch checklist.
• docs/ai-pathway.md: the as-built AI-pathway automation (Coco, gh-aw). docs/github-projects-copilot-automation.md is the original Copilot-based design, kept as background.
• MAINTAINERS.md: who maintains what and how to add a maintainer.