Skip to content

Commit 9836010

Browse files
ehusstraviscross
authored andcommitted
Apply some light edits to the review policy
1 parent d45f393 commit 9836010

File tree

1 file changed

+18
-13
lines changed

1 file changed

+18
-13
lines changed

reference-dev-guide/src/review-policy.md

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,36 @@
1-
Team members are given permission to merge changes from other contributors in the <https://github.com/rust-lang/reference> repository. There are different guidelines for reviewing based on the kind of changes being made:
1+
# Review policy
2+
3+
Team members have permission to merge changes from other contributors in the <https://github.com/rust-lang/reference> repository. There are different guidelines for reviewing based on the kind of changes being made:
24

35
## Review principles
46

57
Reviewers and authors should focus on a few key principles during the review process:
68

7-
* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assumes that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content.
9+
* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assume that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content.
810
* **Defensibility**: When the lang-docs team merges a change to the Reference, they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the Reference. Whenever possible, changes to the Reference should back up any claims with concise examples to verify correctness.
9-
* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc. to fit the Reference before merging if necessary.
11+
* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. As long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc., to fit the Reference before merging if necessary.
1012

1113
## Policy changes
1214

13-
- Significant changes to the policy of how the team operates, such as changes to this document, should have agreement of the team without any blocking objections.
14-
- Minor changes to something like the style enforcement can be made with the review of a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice), and that the change can be easily reversed.
15+
Significant changes to the policy of how the team operates, such as changes to this document, should have the agreement of the team without any blocking objections.
16+
17+
Minor changes to something like style enforcement can be made with the review from a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice) and that the change can be easily reversed.
1518

1619
## Meaningful content addition or changes
1720

18-
- When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct, and consider themselves well-versed enough in the topic to understand it, or the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgement when to consult.
19-
- Content should always follow the guidelines from the [authoring guide].
21+
When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct and considers themselves well-versed enough in the topic to understand it, or if the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgment on when to consult.
22+
23+
Content should always follow the guidelines in this contributor guide.
2024

2125
## Minor content changes
22-
- Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation.
26+
27+
Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation.
2328

2429
## Tooling changes
25-
- Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed.
26-
- Major changes, such as a change in how content is authored, or major changes to how the tooling works should be approved by the team without blocking objections.
30+
31+
Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed.
32+
33+
Major changes, such as a change in how content is authored or major changes to how the tooling works, should be approved by the team without blocking objections.
2734

2835
## Review process flowchart
2936

@@ -47,9 +54,7 @@ Some PRs try to "sell" the language too much, or try to explain more (or less) t
4754

4855
### Is this well written?
4956

50-
Some PRs are right but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge.
57+
Some PRs are correct but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge.
5158

5259
<!-- TODO -->
5360
This policy does not yet cover the process for getting final approval from the relevant teams.
54-
55-
[authoring guide]: authoring.md

0 commit comments

Comments
 (0)