From cf3f0d58be2298f5022901c389e59d462c8d8796 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 24 Oct 2023 09:59:08 +0100 Subject: [PATCH] Add an "MSC Checklist" document and link to it from various places (#4061) --- .../PULL_REQUEST_TEMPLATE/ready-proposal.md | 1 + .github/PULL_REQUEST_TEMPLATE/wip-proposal.md | 1 + MSC_CHECKLIST.md | 50 +++++++++++++++++++ README.md | 3 ++ 4 files changed, 55 insertions(+) create mode 100644 MSC_CHECKLIST.md diff --git a/.github/PULL_REQUEST_TEMPLATE/ready-proposal.md b/.github/PULL_REQUEST_TEMPLATE/ready-proposal.md index b8e262a4..216c58c3 100644 --- a/.github/PULL_REQUEST_TEMPLATE/ready-proposal.md +++ b/.github/PULL_REQUEST_TEMPLATE/ready-proposal.md @@ -16,6 +16,7 @@ assignees: '' * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec-proposals/blob/master/CONTRIBUTING.md#sign-off) * [ ] Update the title and file name of your proposal to match this PR's number (after opening). * [ ] Pull request includes a ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. +* [ ] Your MSC adheres to each point in the [MSC Checklist](MSC_CHECKLIST.md). * [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get feedback on this PR. diff --git a/.github/PULL_REQUEST_TEMPLATE/wip-proposal.md b/.github/PULL_REQUEST_TEMPLATE/wip-proposal.md index 4744c746..3ea86ba5 100644 --- a/.github/PULL_REQUEST_TEMPLATE/wip-proposal.md +++ b/.github/PULL_REQUEST_TEMPLATE/wip-proposal.md @@ -16,5 +16,6 @@ assignees: '' * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec-proposals/blob/master/CONTRIBUTING.md#sign-off) * [ ] Update the title and file name of your proposal to match this PR's number (after opening). * [ ] Pull request includes a ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. +* [ ] Have a look at the [MSC Checklist](MSC_CHECKLIST.md) for guidelines on various aspects of your MSC. diff --git a/MSC_CHECKLIST.md b/MSC_CHECKLIST.md new file mode 100644 index 00000000..30e36436 --- /dev/null +++ b/MSC_CHECKLIST.md @@ -0,0 +1,50 @@ +# MSC Checklist + +This document contains a list of final checks to perform on an MSC before it +is accepted. The purpose is to prevent small clarifications needing to be +made to the MSC after it has already been accepted. + +Spec Core Team (SCT) members, please ensure that all of the following checks +pass before accepting a given Matrix Spec Change (MSC). + +MSC authors, feel free to ask in a thread on your PR or in the +[#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) room for +clarification of any of these points. + +- [ ] Are [appropriate + implementation(s)](https://spec.matrix.org/proposals/#implementing-a-proposal) + specified in the MSC’s PR description? +- [ ] Are all MSCs that this MSC depends on already accepted? +- [ ] For each new endpoint that is introduced: + - [ ] Have authentication requirements been specified? + - [ ] Have rate-limiting requirements been specified? + - [ ] Have guest access requirements been specified? + - [ ] Are error responses specified? + - [ ] Does each error case have a specified `errcode` (e.g. `M_FORBIDDEN`) and HTTP status code? + - [ ] If a new `errcode` is introduced, is it clear that it is new? +- [ ] Will the MSC require a new room version, and if so, has that been made clear? + - [ ] Is the reason for a new room version clearly stated? For example, + modifying the set of redacted fields changes how event IDs are calculated, + thus requiring a new room version. +- [ ] Are backwards-compatibility concerns appropriately addressed? +- [ ] Are the [endpoint conventions](https://spec.matrix.org/latest/appendices/#conventions-for-matrix-apis) honoured? + - [ ] Do HTTP endpoints `use_underscores_like_this`? + - [ ] Will the endpoint return unbounded data? If so, has pagination been considered? + - [ ] If the endpoint utilises pagination, is it consistent with [the + appendices](https://spec.matrix.org/v1.8/appendices/#pagination)? +- [ ] An introduction exists and clearly outlines the problem being solved. + Ideally, the first paragraph should be understandable by a non-technical + audience +- [ ] All outstanding threads are resolved + - [ ] All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative +- [ ] While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely: + - [ ] Introduction + - [ ] Proposal text + - [ ] Potential issues + - [ ] Alternatives + - [ ] Security considerations + - [ ] Dependencies +- [ ] Stable identifiers are used throughout the proposal, except for the unstable prefix section + - [ ] Unstable prefixes [consider](README.md#unstable-prefixes) the awkward accepted-but-not-merged state + - [ ] Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”). +- [ ] Changes have applicable [Sign Off](CONTRIBUTING.md#sign-off) from all authors/editors/contributors diff --git a/README.md b/README.md index ff6d932f..534ed510 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,9 @@ Some tips for MSC writing: effort using [Mermaid](https://mermaid-js.github.io/mermaid/#/). See [this guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) for more information. +* Take a look at the [MSC Checklist](MSC_CHECKLIST.md). When it comes time for + the Spec Core Team to review your MSC for acceptance, they'll use the items + on this checklist as a guide. #### 2. Submitting a Pull Request