From af715106e51707da2231abb826a7f8df99cf90f3 Mon Sep 17 00:00:00 2001 From: austinpower1258 Date: Tue, 29 Sep 2026 00:52:13 -0700 Subject: [PATCH 1/3] docs: require independent change review --- .github/pull_request_template.md | 2 ++ docs/ci/change-management.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 docs/ci/change-management.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ae2d914c39b8..5a524b6827ab 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,8 +33,10 @@ For UI or behavior changes, include a short demo video or screenshots (GitHub up ## Checklist - [ ] Behavior changes have added or updated tests, or Testing says why not +- [ ] An independent reviewer will approve this pull request before merge, or the Summary/Testing section records the specific exception, approver, and reason for merging without approval - [ ] UI, settings, menu, schema, help-text or user-facing docs change: [localization audited](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-localization/SKILL.md), and the result is stated above - [ ] New or changed v2 socket method allowlisted for `cmux ssh`: the [relay authorization questions](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-socket-policy/references/remote-relay-authorization.md) are answered above - [ ] iOS connectivity, auth, lifecycle, workspace action, terminal I/O or mobile RPC contract change: [deterministic soak coverage](https://github.com/manaflow-ai/cmux/blob/main/docs/ios-connectivity-soak.md) updated, or explained why existing coverage still applies, with the affected workload result recorded +- [ ] Changes to `.github/workflows/`, `/ios/Config/`, or `/ios/scripts/upload-testflight.sh` have the required CODEOWNER review before merge - [ ] User-facing docs updated if needed - [ ] Reviewed with a subagent before merge ([cmux-review](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-review/SKILL.md)), and all bot and human review comments resolved diff --git a/docs/ci/change-management.md b/docs/ci/change-management.md new file mode 100644 index 000000000000..33301c72fab2 --- /dev/null +++ b/docs/ci/change-management.md @@ -0,0 +1,31 @@ +# Change management evidence + +cmux changes are merged through GitHub pull requests. The default branch is +protected by a repository ruleset that requires at least one approving review +before a pull request can merge. Pull-request authors cannot approve their own +changes. + +The approval must come from a contributor other than the pull-request author +and must be recorded in GitHub before merge. Reviewers are responsible for +checking the change, its tests, and the stated verification evidence. Changes +to publish-critical or secret-touching paths also require the matching +CODEOWNER review. + +## Exceptions + +An exception is allowed only when the normal reviewer path is unavailable or +would create an incident response delay. The pull request must record all of +the following in its Summary or Testing section before merge: + +- the concrete reason an independent review was unavailable; +- the person who approved the exception; and +- the verification or release review that compensates for the missing review. + +The exception is attached to the pull request and release record so an auditor +can distinguish an approved exception from an unreviewed change. A release +review does not retroactively turn an old pull request into an independently +approved pull request; historical exceptions remain identified as exceptions. + +This document describes the engineering change-management process. It is +operational evidence for the applicable compliance controls and is not a claim +of certification or regulatory approval. From c0e6ab50fdc74f381ac801df3eff05f09c0b2194 Mon Sep 17 00:00:00 2001 From: austinpower1258 Date: Tue, 29 Sep 2026 01:34:25 -0700 Subject: [PATCH 2/3] docs: clarify review exception evidence --- .github/pull_request_template.md | 2 +- docs/ci/change-management.md | 20 +++++++++++++------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5a524b6827ab..77339fc83787 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,7 @@ For UI or behavior changes, include a short demo video or screenshots (GitHub up ## Checklist - [ ] Behavior changes have added or updated tests, or Testing says why not -- [ ] An independent reviewer will approve this pull request before merge, or the Summary/Testing section records the specific exception, approver, and reason for merging without approval +- [ ] An independent reviewer will approve this pull request before merge, or the Summary/Testing section records the specific exception, approver, reason, and compensating verification or release-review evidence - [ ] UI, settings, menu, schema, help-text or user-facing docs change: [localization audited](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-localization/SKILL.md), and the result is stated above - [ ] New or changed v2 socket method allowlisted for `cmux ssh`: the [relay authorization questions](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-socket-policy/references/remote-relay-authorization.md) are answered above - [ ] iOS connectivity, auth, lifecycle, workspace action, terminal I/O or mobile RPC contract change: [deterministic soak coverage](https://github.com/manaflow-ai/cmux/blob/main/docs/ios-connectivity-soak.md) updated, or explained why existing coverage still applies, with the affected workload result recorded diff --git a/docs/ci/change-management.md b/docs/ci/change-management.md index 33301c72fab2..776260c92e5b 100644 --- a/docs/ci/change-management.md +++ b/docs/ci/change-management.md @@ -13,18 +13,24 @@ CODEOWNER review. ## Exceptions -An exception is allowed only when the normal reviewer path is unavailable or -would create an incident response delay. The pull request must record all of -the following in its Summary or Testing section before merge: +Historical or incident exceptions are recorded when the normal reviewer path +was unavailable or would have created an incident response delay. The pull +request must record all of the following in its Summary or Testing section: - the concrete reason an independent review was unavailable; - the person who approved the exception; and - the verification or release review that compensates for the missing review. -The exception is attached to the pull request and release record so an auditor -can distinguish an approved exception from an unreviewed change. A release -review does not retroactively turn an old pull request into an independently -approved pull request; historical exceptions remain identified as exceptions. +The active default-branch rulesets require one approving review, dismiss stale +approvals, require approval of the last push, and have no bypass actors. An +exception note does not waive that gate or authorize an author or maintainer to +merge without the required review. If the normal reviewer path is unavailable, +hold the merge until an independent reviewer is available. For a historical or +separately approved incident exception that already merged outside the gate, +attach the exception to the pull request and release record so an auditor can +distinguish it from an unreviewed change. A release review does not +retroactively turn an old pull request into an independently approved pull +request; historical exceptions remain identified as exceptions. This document describes the engineering change-management process. It is operational evidence for the applicable compliance controls and is not a claim From 7da94a68fa52b557800dbdd6889c91f5bbdf864d Mon Sep 17 00:00:00 2001 From: austinpower1258 Date: Tue, 29 Sep 2026 01:52:07 -0700 Subject: [PATCH 3/3] docs: keep review approval mandatory --- .github/pull_request_template.md | 3 ++- docs/ci/change-management.md | 23 +++++++++++++---------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 77339fc83787..1ee9fc43fa0e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,8 @@ For UI or behavior changes, include a short demo video or screenshots (GitHub up ## Checklist - [ ] Behavior changes have added or updated tests, or Testing says why not -- [ ] An independent reviewer will approve this pull request before merge, or the Summary/Testing section records the specific exception, approver, reason, and compensating verification or release-review evidence +- [ ] An independent reviewer will approve this pull request before merge +- [ ] If this pull request documents a historical or incident exception, the Summary/Testing section records the specific exception, approver, reason, and compensating verification or release-review evidence; that record does not replace the required approval - [ ] UI, settings, menu, schema, help-text or user-facing docs change: [localization audited](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-localization/SKILL.md), and the result is stated above - [ ] New or changed v2 socket method allowlisted for `cmux ssh`: the [relay authorization questions](https://github.com/manaflow-ai/cmux/blob/main/skills/cmux-socket-policy/references/remote-relay-authorization.md) are answered above - [ ] iOS connectivity, auth, lifecycle, workspace action, terminal I/O or mobile RPC contract change: [deterministic soak coverage](https://github.com/manaflow-ai/cmux/blob/main/docs/ios-connectivity-soak.md) updated, or explained why existing coverage still applies, with the affected workload result recorded diff --git a/docs/ci/change-management.md b/docs/ci/change-management.md index 776260c92e5b..cb22585c6225 100644 --- a/docs/ci/change-management.md +++ b/docs/ci/change-management.md @@ -21,16 +21,19 @@ request must record all of the following in its Summary or Testing section: - the person who approved the exception; and - the verification or release review that compensates for the missing review. -The active default-branch rulesets require one approving review, dismiss stale -approvals, require approval of the last push, and have no bypass actors. An -exception note does not waive that gate or authorize an author or maintainer to -merge without the required review. If the normal reviewer path is unavailable, -hold the merge until an independent reviewer is available. For a historical or -separately approved incident exception that already merged outside the gate, -attach the exception to the pull request and release record so an auditor can -distinguish it from an unreviewed change. A release review does not -retroactively turn an old pull request into an independently approved pull -request; historical exceptions remain identified as exceptions. +The linked repositories enforce the review gate through their GitHub branch +protection configuration; the live settings and their Vanta evidence are +recorded in [issue #15527](https://github.com/manaflow-ai/cmux/issues/15527). +This document describes the process and does not define or override those +repository settings. An exception note does not waive the gate or authorize an +author or maintainer to merge without the required review. If the normal +reviewer path is unavailable, hold the merge until an independent reviewer is +available. For a historical or separately approved incident exception that +already merged outside the gate, attach the exception to the pull request and +release record so an auditor can distinguish it from an unreviewed change. A +release review does not retroactively turn an old pull request into an +independently approved pull request; historical exceptions remain identified as +exceptions. This document describes the engineering change-management process. It is operational evidence for the applicable compliance controls and is not a claim