diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db25d083..352c2a41 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,3 +9,48 @@ Contributions to Student Robotics' Runbook should: [code-of conduct]: https://opsmanual.studentrobotics.org/about-the-charity/code-of-conduct [license]: ./LICENSE [contribution-guide]: docs/contributing.md + +## Review Process + +We should aim to keep review as lightweight as possible, with a bias towards +getting content live over making it perfect. + +We do however want to review the content which is contributed for two reasons: + +* content that is substantially unclear or actually wrong will do more harm than + a lack of documentation + +* some of the content here covers sensitive topics such as safety measures at + events or safeguarding; it is especially important that documentation of these + areas is correct & clear, warranting more scrutiny + +The following protocol (in line with how GitHub describe these terms) is +therefore proposed for review: + +* _Approval_ responses mean "this change can merge as is" but may include + additional suggestions. Contributors may reject these suggestions, but are + expected to respond to them before merging if that is the case. Discussion of + these suggestions may continue after the PR is merged. + +* _Comment_ responses are non-blocking, but also not approval, typically to ask + questions about the content or suggest improvements. Such responses may + indicate a review only of some part of the content. + +* _Request changes_: responses are blocking and indicate that changes are needed + before content can be merged. The review should indicate, either in the + summary comment or in the inline comments, which of the issues raised are + blocking. Such responses should be rare. + +In general reviewers are encouraged to bias in favour of merging unless they +feel that the change is particularly sensitive or would be a net negative to the +runbook. + +### Practicalities of Review + +* Please do choose reviewers when opening a PR, ideally by subject matter but if + in doubt pick one of the maintainers (@PeterJCLaw or @RealOrangeOne) and they + can redirect +* Please do use GitHub's tooling to ask for re-review after changes +* After review the contributor is typically responsible for performing the merge + themselves. New contributors (who may not have write access) should ping one + of the maintainers or reviewers to do this instead.