Reviewing and being reviewed #

Review is where most of the learning in an open source project happens, in both directions.

Contents #

1. Being reviewed
2. Squash and rebase
3. Reviewing others
4. Feedback within the code of conduct

Being reviewed #

"Be prepared for many review rounds. 7x does a much larger than usual number of review rounds before it accepts a commit or pull request, sometimes hundreds of revisions. [...] This is how the kernel stays maintainable; it is not a judgment of you." (CONTRIBUTING.md, "Code Reviews")

To get through review faster (same source):

• Keep pull requests small and focused: one change per pull request.
• Follow the coding standards and the style of the files around your change.
• Add tests that fail without your change and pass with it.
• Answer every review comment in the pull request, with a change or a reason.
• Keep your branch current: rebase it on main before asking for the next round.
• Do not take many rounds personally.
• If your change alters a negative feature, behavior that is deliberate or open to interpretation and that other sites depend on, expect more rounds still: justify the use case, and offer the new behavior as an option rather than a new default.

Every pull request is merged in the end: its author revises it as the reviews ask (How the project grows).

Squash and rebase #

7x requires that you "squash and rebase your pull request onto main while it is open":

git fetch origin
git rebase -i origin/main          # fold fixups into logical commits, usually one
git push --force-with-lease        # only to your own pull request branch, never to main

Once a pull request is merged, main's history is never rewritten; a later fix comes as a new pull request.

Reviewing others #

Community members can review pull requests too, and a careful review from a user of the affected feature helps the maintainers:

Write what you tested and on what setup. "Tested on PHP 8.3, SQLite, Velocity: works" is useful; "Looks good" is not. More: Reviewing other people's work.

Feedback within the code of conduct #

• Comment on the code, never on the person.
• Explain why, and suggest an alternative.
• Disagree "on technical merits, in public, and politely" (CODE_OF_CONDUCT.md, "The contributor agreement (CLA)").
• Thank people for their work, also when you ask for changes.

Related pages #

• Contributing code
• Pull request etiquette
• Mentoring
• The code of conduct
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.