Review policy

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:

Review principles

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

• Understandability: Prose 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.
• 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.
• 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.

Policy changes

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.

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.

Meaningful content addition or changes

When adding or changing content in the Reference, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence in the correctness of the changes, if the reviewer is well-versed in the topic, or if the relevant experts are already the author of or actively involved in the PR. It is up to the reviewer to use good judgment on when to consult.

Content should always follow the guidelines in this contributor guide.

Minor content changes

For minor content changes --- such as small cleanups, wording fixes, or formatting corrections --- a maintainer may push fixes directly to the PR branch and merge, without consulting the author or other reviewers.

Tooling changes

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.

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.

Review process flowchart

When reviewing a pull request, ask yourself the following questions:

Are the proposed changes true?

If we‘re not sure and can’t easily verify it ourselves, we ask someone who would know.

Does this make any new guarantees about the language?

If this would make a new guarantee about the language, this needs to go through the lang team to be accepted (unless the lang team has clearly accepted this guarantee elsewhere). Ask @traviscross if at all unsure about any of these.

Would we have added this to the Reference ourselves?

There are a number of PRs that might be true, but when we look at them, we think to ourselves, in our heart of hearts, that this just isn‘t something we would have bothered to write ourselves. We don’t want to accept a PR just because it's in front of us and not obviously false. It should clearly add value.

Is this editorially sound?

Some PRs try to “sell” the language too much, or try to explain more (or less) than needed, or give too many (or too few) examples, etc. The PR should match the general flavor of the Reference here.

Is this well written?

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.

This policy does not yet cover the process for getting final approval from the relevant teams.