diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..8040bed0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,102 @@ +## Contributing to the Matter Handbook + +Welcome - thanks for taking the time to improve the Matter Handbook. + +> [!NOTE] +> For questions, clarifications, or early ideas, start a Discussion instead of opening an Issue; +> Issues are reserved for concrete, actionable work items. + +--- + +### Summary + +The contribution process is intentionally lightweight and entirely pull‑request (PR) based: +every change - large or small, including typo fixes - comes in as a PR so it can be reviewed, validated by automation, +and merged transparently. + +Classify the change with the most specific label (`editorial`, `tooling`, or one or more domain labels; +add `do not merge` only when you deliberately want to block). Every PR requires at least one maintainer approval. +When a domain label is present, the external `sme-approval` check must also succeed, confirming that the appropriate +subject‑matter experts have signed off. All mandatory automated checks (including Vale) must be green, +there must be zero unresolved review threads and no active “changes requested” reviews, +the PR cannot be in draft state or have merge conflicts, and the blocking `do not merge` label must be absent. +Once these conditions are satisfied, the merge is performed automatically—no further manual action is needed. +If you are new to GitHub: a PR is simply a proposed set of changes that others can comment on before it is merged. + +--- + +All changes flow through this PR pipeline (there is no direct push to main, even for small editorial tweaks); +this ensures consistency, traceability, and required approvals without extra ceremony for contributors +who are less familiar with GitHub. + +### Git Workflow + +| Contributor type | Branch location | How to create | After merge | Rationale | +|------------------|-----------------|---------------|-------------|-----------| +| Frequent (granted write access) | Branch in this repository | `git switch -c feature-short-description` (from up-to-date `main`) | Auto-deleted by settings / cleanup | Faster feedback, no fork sync overhead | +| Infrequent / first-time | Fork (user namespace) | Fork on GitHub UI, clone fork, branch there | Branch stays in fork; can be deleted manually | Keeps main repository branch list focused | + +Guidelines: +- Keep branches short-lived and narrowly scoped; open earlier rather than accumulating a large diff. +- Update your local copy of `main` before branching (fetch and integrate the latest changes) to reduce conflicts. +- Do not force-push over reviewed commits. +- Name branches descriptively and succinctly (e.g. `certification-diagram`, `tooling-ci-cache`, `editorial-typos`). +- One logical change per PR—open multiple PRs instead of a “grab bag”. +- Frequent contributors should still fork when experimenting in a way that may not merge. +- Delete local and remote branches after merge (the repository auto-deletes remote branches; you can prune locally with `git fetch --prune`). + +If you become a frequent contributor, maintainers may grant write access so you can use the streamlined in-repo branching workflow. This is a trust signal. Maintain clear commit hygiene and respond promptly to review. + +### Labels + +| If your change… | Use this label | Extra gate | +|-----------------|---------------|------------| +| Pure wording / typos / formatting (no meaning change) | `editorial` | Maintainer approval | +| CI, workflows, devcontainer, build infra | `tooling` | Maintainer approval | +| Semantic/content change in a domain (e.g. certification) | Domain label (e.g. `certification`) | Maintainer approval + `sme-approval` | +| Needs a temporary hold | `do not merge` | Blocks merge | + +Rules: +- If a change has any semantic impact, use a domain label (not `editorial`). +- Multiple domain labels allowed; external check enforces SME coverage. +- Do not remove a domain label to bypass review. + +--- + +### Merge Conditions + +All must be true for auto‑merge: +- Maintainer approval present. +- If domain label: `sme-approval` succeeded. +- Vale success. +- No unresolved review threads (`#review-threads-unresolved=0`). +- No “changes requested” reviews. +- Not draft; no merge conflicts. +- No `do not merge` label. + +--- + +### Roles + +| Role | Responsibility | +|------|----------------| +| Author | Correct labels, clear scope, address feedback | +| Maintainer | Process, risk, coherence | +| SME (external) | Domain accuracy (per domain label) | + +--- + +### Review Discipline + +- Resolve threads only after action or explicit agreement. +- Keep scope tight; split unrelated chunks. +- Avoid large force-pushes mid-review (cleanup near the end is fine). +- Do not game the process by dropping needed labels. + +--- + +### Escalation + +If blocked >5 business days: +- Comment and mention `@project-chip/handbook-maintainers`. +- Open a Discussion for structural or multi-domain proposals.