From 30aa2efb5314f4f66c33c29a37395275a12a9ac2 Mon Sep 17 00:00:00 2001 From: Thomas Hartwig Date: Tue, 7 Oct 2025 16:46:11 +0200 Subject: [PATCH 1/4] Add CONTRIBUTING.md Adding a CONTRIBUTING.md file that outlines the editorial process for adding new content or modifying the existing Matter Handbook content. --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ab324605 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +## 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-aproval` 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. + +### 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-aproval` | +| Needs a temporary hold | `do not merge` | Blocks merge | + +Rules: +- Any semantic impact then use a domain label (not `editorial`). +- Multiple domain labels allowed; external check enforces SME coverage. +- Don’t remove a domain label to bypass review. + +--- + +### Merge Conditions + +All must be true for auto‑merge: +- Maintainer approval present. +- If domain label: `sme-aproval` 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). +- Don’t 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. From c8fbc53eb6ae02dec639506cd7156a814efbc51a Mon Sep 17 00:00:00 2001 From: Thomas Hartwig Date: Tue, 7 Oct 2025 16:57:17 +0200 Subject: [PATCH 2/4] Add Git Workflow Section --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab324605..c71678a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,24 @@ All changes flow through this PR pipeline (there is no direct push to main, even 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 | From 68713907ace53fd50652e277990c8e5ea4beb484 Mon Sep 17 00:00:00 2001 From: Thomas Hartwig Date: Tue, 7 Oct 2025 17:34:02 +0200 Subject: [PATCH 3/4] Apply Suggestions From Code Review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c71678a1..ac837260 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ Guidelines: - 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. +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 @@ -57,9 +57,9 @@ If you become a frequent contributor, maintainers may grant write access so you | Needs a temporary hold | `do not merge` | Blocks merge | Rules: -- Any semantic impact then use a domain label (not `editorial`). +- If a change has any semantic impact, use a domain label (not `editorial`). - Multiple domain labels allowed; external check enforces SME coverage. -- Don’t remove a domain label to bypass review. +- Do not remove a domain label to bypass review. --- @@ -91,7 +91,7 @@ All must be true for auto‑merge: - 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). -- Don’t game the process by dropping needed labels. +- Do not game the process by dropping needed labels. --- From 111a7398b4dfbdfc39533807f51eec42f6ddfd5e Mon Sep 17 00:00:00 2001 From: Thomas Hartwig Date: Tue, 7 Oct 2025 17:35:33 +0200 Subject: [PATCH 4/4] Fix Spelling Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac837260..8040bed0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ 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-aproval` check must also succeed, confirming that the appropriate +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. @@ -53,7 +53,7 @@ If you become a frequent contributor, maintainers may grant write access so you |-----------------|---------------|------------| | 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-aproval` | +| 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: @@ -67,7 +67,7 @@ Rules: All must be true for auto‑merge: - Maintainer approval present. -- If domain label: `sme-aproval` succeeded. +- If domain label: `sme-approval` succeeded. - Vale success. - No unresolved review threads (`#review-threads-unresolved=0`). - No “changes requested” reviews.