Project:Reviewers/Internal policy

This document lists the policies which Reviewers team members are ought to follow.

Review platforms

The Reviewers project members review:

• pull requests and commits on the GitHub repository mirror (if commit author actively uses GitHub),
• commits done to the repository, by replying to gentoo-commits mails,
• requested ebuilds pasted on Gentoo Bugzilla, IRC and Gentoo Forums.

The review should be done most efficiently to avoid 'spamming' the contributor unnecessarily. In case of review-by-mail, the review should be only directed to the affected parties, unless it can be useful to a wider audience. In the latter case, it may be a good idea to send a single mail to gentoo-dev mailing list as an example of common issue and a sufficient explanation.

Review process

Most importantly, use common sense. Figure out what is the maintainer's attitude towards further contributions. Focus on new code and changes. However, if maintainer is willing, encourage him to fix existing issues with the code.

Focus on issues. You can also point out how readability can be improved, or code can be optimized but don't go against maintainer's preferences. Do not nitpick on style, unless it is strongly enforced in Gentoo (i.e. use of tabs vs spaces).

Remember that the main goal of review is to teach. Provide good explanations, with examples or pseudo-code if possible. Remember that English is not the native language for most contributors and developers, so try to speak plain, 'international' English and support your statements with code.

The Reviewers project holds no special powers in Gentoo, so don't try to force anything. If you see major QA or Security issues with a particular commit, ask the appropriate projects to handle them.

Doubts and problems

Not everyone is all-knowing. When in doubt, either consult the relevant documentation or ask other Reviewers for help. If you choose to do the latter, prefer private communication channels not to 'spam' the review unnecessarily or confuse the user.

When the code submitted by user is unclear or simply 'fishy', ask him about it. If it can be improved, suggest how to improve it. If it can't, ask the user to add an explanatory comment to save other developers from having to wonder about it in the future.