(see also How To Submit Patches)

Why review patches

We want more patches to be contributed to Tahoe-LAFS. Having patches languishing in the "waiting to be reviewed" state discourages contributors. Getting feedback on patches encourages them. (By the way, something else that encourages them is users saying "Thank you.".)

Who can review patches

Pretty much anyone reading this! Knowledge of Python is helpful, but some patches are so simple that reviewing them is a reasonable task for a beginner who is learning Python. Some patches require more specialized knowledge to review, but most don't.

How to review patches

Here is the overall process for patch review. For technical tips, see below.

1. Go to ​https://tahoe-lafs.org . Click on "View Tickets". Click on "review-needed".
2. You can read everything without registering, but to add comments or change tickets you have to be logged in. Registering is easy -- click the "Register" link at the top right of the page.
3. Read tickets until you find one that you can review.
4. (optional) Expand "modify ticket" and click "accept", then submit changes. This marks you as the person reviewing this patch. If you don't want to commit to this then you can skip this step.
5. Read the patch until you understand the docs, tests, code and comments in it. (You can use the "Browse source" button at the top of the page to read the current versions of the files that the patch changes.) Post comments on the trac ticket as you go. If there's something good or bad in the patch you're reviewing, then you'll know it when you see it.
   1. If you can't understand the patch after spending some time on it, then say so in a comment on the ticket! This might mean that we need to add documentation or comments or to refactor the code. On the other hand, it might just be that you don't have enough context to understand the code. That's okay too, so go ahead and speak up.
   2. Check whether every feature or bugfix in the patch has an accompanying test in the patch.
   3. If you find errors or omissions in the docs, tests, code or comments then write that down in the ticket, remove the review-needed keyword from the keywords, and add the test-needed keyword if that applies. Then assign the ticket to someone other than yourself. (Assign it to the original author of the patch, or someone who seems likely to fix the patch, or "nobody".)
   4. If you understand the patch and find no errors or omissions then write a comment on the ticket saying that you reviewed it, remove the keyword review-needed, add the keyword reviewed, and assign it to someone with repository write access (currently 'zooko', 'warner', 'daira', and 'kevan'). We'll commit it to trunk.
   5. Feel good about yourself. Thank you for helping with our little project attempting to improve the world!

Advanced

Once you decide that you like reviewing tickets and you get into the habit of doing it frequently, then read this essay by Jonathan Lange on how to do it well: ​Your Code Sucks and I Hate You: The Social Dynamics of Code Reviews.

A few simple suggestions:

1. Thank the author for writing the patch.
2. Say something nice about the author or their code.
3. You don't have to be extra picky when doing patch review. The goal is just to watch out for bugs or things that would reduce the quality of the codebase.
4. Write comments about specific parts of the code. This demonstrates that you actually read it carefully enough to understand and care about parts of it, and it makes the author feel good that someone is talking about what they wrote.

Experiment: Suspicious Patch Review

Maybe it would be fun to imagine, while you're reviewing a patch, that the author has been compelled to slip a Trojan into the patch by evil adversaries, and it is your job to notice it! That's why you are motivated to request that the author rewrite or explain any confusing parts, because any parts of the patch that confuse the code-reviewer are parts where a Trojan could slip through. Of course, well-written Trojans are indistinguishable from normal old innocent bugs, so if you find a bug this way, give the author the benefit of the doubt and assume that it was an honest mistake.

Using trac and github

The patch you're reviewing might be given either as an attachment, or as a github pull request. If it's the latter, then it's encouraged to use line comments on github for detailed comments or questions on the code. However, you should also write a short summary of the review on the trac ticket. (Sometimes this can be as simple as "+1" if there are no further issues to discuss.)

In all cases it's recommended to apply the patch or check out the code and run the full test suite locally (using python setup.py test since a rebuild is usually necessary), to check that it passes. You'd be surprised how often a patch author thinks it passes tests, but a "harmless" last-minute change, a portability problem, or a nondeterministic race condition causes it to fail when checked. (There's usually no need to test on multiple platforms at this stage though -- that's what the buildbots are for.) All committed code should also be free of pyflakes errors or warnings.