diff --git a/MAINTAINING.md b/MAINTAINING.md index f403f58fa7..c4379f9e85 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -1,11 +1,11 @@ # RIOT Maintainer Guidelines -This list presents a series of guidelines for maintainers, including technical -and non-technical. The list is not exhaustive, and represents a baseline on +This list presents a series of technical and non-technical guidelines for maintainers. +The list is not exhaustive, it represents a baseline on things that should be ensured for contributions. Notes: -- Any of the items in this list might be skipped, if clearly and logically +- Any of the items in this list can be skipped, if clearly and logically articulated reasons are presented. - The order of the steps is meant to maximize efficiency and minimize overhead, with the philosophy that failing in step n makes steps n+x @@ -14,9 +14,9 @@ Notes: state (for example, due to poor code cleanliness or overall design), it might be more efficient to give the contributor some broader comments for improvement before further review. -- This is a working document and any changes, additions, or other discussions +- This is a working document: any changes, additions, or other discussions are encouraged, via PRs raised against the document. Changes to this - document should however have at least two ACKs, to ensure these guidelines + document should have at least two ACKs, to ensure these guidelines are well thought out, and that they reflect community consensus. The [list of maintainers] gives information on the current maintainers and the @@ -54,7 +54,7 @@ the overall validity of the PR. ### 2. - Review the design of the code -The following list is not exhaustive and addresses the coding issues we have +The following list is not exhaustive, it addresses the coding issues we have regularly seen in the past. In particular, check that the [Best Practices] are followed. These checks can be aided (but not replaced) by a tool such as Coccinelle, using the script found in dist/tools/coccinelle. @@ -116,7 +116,7 @@ complete that no input from the original developer or maintainer is required. means we are investing in our community. - Be friendly. Respect the original author, bearing in mind that their coding style or their design may be just as valid as the way you would have done - it. And of course, always follow the [Code of Conduct]. + it and of course, always follow the [Code of Conduct]. ### Organisation of reviewing between maintainers @@ -130,14 +130,14 @@ Rather, give your verbal ACK and describe what you reviewed. In addition, if you processed or reasonably stepped over a whole section, mark the PR with the according label from the "Reviewed:" category. If you set a label by stepping over a section, please articulate your reasoning for this clearly, as noted in -the [introduction](#introduction). This will help other maintainers help to +the [introduction](#introduction). This will help other maintainers to better understand your line of thought. If you disagree with the assessment of a previous review, you may remove a certain "Reviewed:" label. Please state your reasoning in this case as well. When all "Reviewed:" labels are set you may give your approval for the PR. -As everything in this document this is a "CAN", not a "MUST": It might help +As for everything in this document this is a "CAN", not a "MUST": It might help other maintainers to track your work, but if the overhead isn't justified, a simple approving ACK might suffice.