Cleanup maintainer handbook (#287)

project/maintainers.md

@@ -8,12 +8,12 @@ provide a consistent user interface for those going through the review process.
 
 ## The Pull Request
 
-Pull requests are submitted through GitHub.  They are contributions to change
-the project.  There is no difference between code and non-code submissions, in
+Pull requests are submitted through GitHub. They are contributions to change
+the project. There is no difference between code and non-code submissions, in
 procedure or policy.
 
-All maintainers should consider that pull requests are gifts.  The project
-survives due to the effort of frequent contributors and their generosity.  As
+All maintainers should consider that pull requests are gifts. The project
+survives due to the effort of frequent contributors and their generosity. As
 such, to encourage future submissions, the default approach to handling a merge
 request should be gratitude, even if the request cannot be merged.
 
@@ -25,63 +25,63 @@ There are two primary roles within the scope of a pull request.
 - Maintainer - one who merges the code.
 
 To ensure that all code receives a proper review, these roles are mutually
-exclusive for each pull request.  Within the scope of a pull request, a
+exclusive for each pull request. Within the scope of a pull request, a
 Committer cannot be a Maintainer, nor can a Maintainer be a Committer.
 
 For abandoned pull requests still requiring work, or efforts transferred between
 people, a Maintainer may become a Committer, invalidating any of their prior
-review work.  
+review work. 
 
 ### Committers
 
-Committers are people contributing changes to the repository.  The first
-committer is typically the one that opens the pull request.  Additional people
+Committers are people contributing changes to the repository. The first
+committer is typically the one that opens the pull request. Additional people
 can become committers in the same merge request if they change the pull request
 directly.
 
 Suggestions to a committer by a maintainer, such as commentary that with a
 change the merge request might be accepted, does not make a maintainer a
-committer, as the committer will choose include the change at their discretion. 
+committer, as the committer will choose to include the change at their discretion.
 
 ### Maintainers
 
-Maintainers hold a dual role in the project.  They are ambassadors of the
-effort as well as the gatekeepers permitting changes to the repository.  As
+Maintainers hold a dual role in the project. They are ambassadors of the
+effort as well as the gatekeepers permitting changes to the repository. As
 ambassadors, maintainers must present a fair and impartial demeanor when
 dealing with contributors.
 
 Failure to be fair or impartial reflects poorly on the released product, as
-guilt by association taints the product.  The process of reviewing a merge
-request often includes conflict.  Contributors can become defensive about work
+guilt by association taints the product. The process of reviewing a merge
+request often includes conflict. Contributors can become defensive about work
 they've done while maintainers can become adamant in the changes they request.
 
 To prevent a breakdown in the review process, the project encourages all
-reviewers to adhere to a standard set of review best practices.  Reviewers
+reviewers to adhere to a standard set of review best practices. Reviewers
 should familiarize themselves with these practices and suggest updates to keep
 the practices relevant over time.
 
 ## Review Standards
 
-These standards serve to prevent problems from cropping up during a review.  The 
+These standards serve to prevent problems from cropping up during a review. The 
 intent is that consistent application of these standards permits a consistent 
 review process, leading to repeatable, suprise free, outcomes during a review.
 
 The intent of maintaining standards is to enhance productivity and improve team
-morale.  In the event the standards have a negative impact on productivity or
-morale, the standard itself should be questioned.  To clarify the kinds of
+morale. In the event the standards have a negative impact on productivity or
+morale, the standard itself should be questioned. To clarify the kinds of
 productivity to be improved, the intent is to reduce the time between initial
 submission of a merge request and its resolution.
 
 ### Challenges to the Review Process
 
 Whenever possible, a maintainer should not argue a point about the review
-standards with a contributor.  Instead they should provide this document to the
+standards with a contributor. Instead they should provide this document to the
 contributor, indicating that changes to the review process are to be initiated
 with a standard-altering Issue.
 
 In the exceedingly rare situation that a reviewer opts to ignore a review
 standard during a merge request, the reviewer must indicate they are purposefully
-ignoring the standard and the reason why.  There are valid reasons to ignore
+ignoring the standard and the reason why. There are valid reasons to ignore
 standards, but whenever possible a maintainer should uphold the standard or
 change it.
 
@@ -102,20 +102,20 @@ being suggested.
 
 ### Review Tempo
 
-Maintainers should set aside and appropriate amount of time when reviewing.  The
-initial suggestion is one hour.  Most reviews will complete well under this time,
-but a few will take longer.  Longer reviews should include review breaks, so the
-reviewer remains fresh and attentive.  Attempting a three hour long review often
+Maintainers should set aside and appropriate amount of time when reviewing. The
+initial suggestion is one hour. Most reviews will complete well under this time,
+but a few will take longer. Longer reviews should include review breaks, so the
+reviewer remains fresh and attentive. Attempting a three hour long review often
 yields worse results than two or three shorter efforts with breaks.
 
-The concept of going slow to complete items quickly is not a new one.  With a
+The concept of going slow to complete items quickly is not a new one. With a
 little extra time, comments can be thoughtful instead of reactive.
 
 ### Review Goals
 
 Each review should have a defined set of goals established prior to the main
-work of the review.  The review process often challenges the committer, in the
-hopes of improving the merge request.  Keeping the review scoped to goals avoids
+work of the review. The review process often challenges the committer, in the
+hopes of improving the merge request. Keeping the review scoped to goals avoids
 scenarios where the reviewer's requests seem capricious or autocratic.
 
 The current list of review goals include:
@@ -141,20 +141,20 @@ goals.
 
 Each submission should assume that the committer ran the unit tests and 
 small-scale (not requiring an environment) integration tests prior to submission.
-The merge request CI pipeline also runs these tests automatically.  Failure to
+The merge request CI pipeline also runs these tests automatically. Failure to
 pass them leads to an automatic call for merge request modification.
 
 Attempts to pass this requirement by disabling tests or modifying them such that
-they are effectively disabled are strongly discouraged.  They violate the review
+they are effectively disabled are strongly discouraged. They violate the review
 goals by reducing maintainability (no new failures will be detected) and
 possibly functionality (for scenarios outside of the current mindset).
 
-At their leisure, maintainers may suggest code changes make the test suite pass.
+At their leisure, maintainers may suggest code changes to make the test suite pass.
 Doing so is never required, nor part of the minimum duties of a maintainer.
 
 ### Reviewer Count
 
-Two passing reviews are required for code to be merged.  
+Two passing reviews are required for code to be merged. 
 
 Whenever possible, the number of reviewers should be limited, as each additional
 reviewer presents an extra set of communication channels between the review and
@@ -170,20 +170,20 @@ themselves.
 
 The amount of possible communication grows such that 
 `commChannels(reviewers) = reviewers + reviewers(reviewers-1)/2` leads to an 
-`O(n^2)` number of channels.  Thus, keeping reviewer count low is critical to
+`O(n^2)` number of channels. Thus, keeping reviewer count low is critical to
 velocity.
 
 ### Reviewer Consensus
 
 Reviewers should coordinate among themselves when differences of opinion arise
-in a review.  The first reviewer is likely to make a statement before being
+in a review. The first reviewer is likely to make a statement before being
 aware of the difference of opinion; but, once a difference of opinion is known,
 the reviewers should coordinate privately to find a unified presentation of the
 desired features to communicate back to the committer.
 
 The committer has no role in the evaluation of options to determine the proper
 path forward, including them only diminishes the efficiency of the process and
-increases the stress they endure while they observe the discussion.  Once a path
+increases the stress they endure while they observe the discussion. Once a path
 is agreed upon:
 
 - If the request to the committer was reversed, the reviewer making that stance
@@ -192,8 +192,8 @@ is agreed upon:
   present the refined path.
 
 If no path forward can be agreed upon, the proposed path that is closest to the
-committer submission is the accepted path.  This guideline exists to promote
-cooperation among reviewers.  Ideas of merit which don't become part of the
+committer submission is the accepted path. This guideline exists to promote
+cooperation among reviewers. Ideas of merit which don't become part of the
 merge request should be submitted as new issues and reviewed independently.
 
 ### Review Automation
@@ -204,9 +204,9 @@ review process by automating a portion of the process, the reviewer should
 create an issue and submit it as an improvement to the CI process.
 
 Improvements are subject to the same review process and the same review goals
-as other committer offerings.  Readability, search-ability, understanding,
+as other committer offerings. Readability, search-ability, understanding,
 maintenance, testing, and functionality are goals of the review process just as
-they are of the product code.  
+they are of the product code. 
 
 Lack of speed in the review process is viewed as a failure to make the process
 maintainable, understandable, and functional.
@@ -214,8 +214,8 @@ maintainable, understandable, and functional.
 ### Review Communication
 
 Reviewers are encouraged to have meaningful dialogues with contributors and
-reviewers during a merge request.  For these dialogues to be effective, the
-purpose of each communication should be considered.  Mixing purposes in
+reviewers during a merge request. For these dialogues to be effective, the
+purpose of each communication should be considered. Mixing purposes in
 communication creates problems in understanding intent, retarding progress.
 Scope your communications to move efforts forward.
 
@@ -228,10 +228,10 @@ Avoid mixing the following communication scopes:
 - Information sharing
 - Brainstorming
 
-Combining these scopes reduce the effectiveness of the communication.  Ideally
-they should be done in different settings.  Mixing a brainstorming session with
+Combining these scopes reduce the effectiveness of the communication. Ideally
+they should be done in different settings. Mixing a brainstorming session with
 a decision making session disrupts the evaluation of pros and cons with new
-options.  Attempting to problem solve a technical issue during a status update
+options. Attempting to problem solve a technical issue during a status update
 draws focus away from identifying the challenges of delivering the project,
 replacing them with the challenges of solving a single problem in the project.