Agenda for a patch review event

Last updated on

11 March 2021

This documentation needs work. See "Help improve this page" in the sidebar.

What is a patch review event?

A patch review event is getting people together for a set amount of time – anywhere from a couple of hours to a couple of days – to review code contributions, which could be patches, pull requests, or issue branches associated with issues in the Drupal core project, or contributed module, theme, and distribution projects. In this page, the word "patch" is used to refer to a proposed code change, in any of these formats.

Patch review events offer a great learning experience, as they help expose people to many parts of Drupal they may not otherwise have had access to. They are also a lot of fun, as they get folks talking and working directly with experienced contributors and having a good time making Drupal better!

This page gives an overview of the review process (see the general contribution event organizing page for other suggestions about organizing contribution events), the list of prerequisites participants need to have in place, and a list of commands for use while patch reviewing. Please note that "coding skills" is not on the list of prerequisites. While people with coding skills can perform certain types of reviews better than non-coders, non-coders can also perform certain types of reviews better than coders. In short: everyone is welcome!

Overview of reviewing

The goal of the event is to reduce the number of issues at Needs Review status for a project down to zero (or as close to it as possible); see the Issue status field page for more details on status values. To do a review, first find the issues for a project, then filter to Needs review status. Choose an issue from the list that seems interesting, and apply the patch to test it out. If you're looking for a patch to review in a specific area of interest, you can also limit the list by component (such as "user interface" or "documentation") or glance through the Drupal core community initiatives pages for specific topical areas. Using the advanced issue search, you can also filter to issues with the "Novice tag", which should be issues appropriate for new contributors, which only change minor things and should be fairly easy to review if you're new to contributing.

As a patch reviewer, your primary objective is to find a reason to mark a patch "needs work." Some reasons for doing so include:

The patch has grammar or spelling mistakes.
The patch does not work when viewed in browsers such as Safari, IE, or Opera.
The patch causes errors when applied to your copy of Drupal.
When trying something crafty to out-smart the original patch author, you come across unintended behaviour.
The resulting user interface is obtuse and difficult to use.
The code doesn't conform to coding standards.
The changes are insufficiently documented and/or difficult to understand.
The patch does not contain tests to prove a new feature works, and/or a bug stays fixed.

If, and only if, you can find nothing wrong with the patch after trying really hard to do so, then you mark it "reviewed & tested by the community."

Regardless of the outcome of the patch review, document carefully in your reply all of the things you tried and what results you achieved, things you liked about the patch, things you did not like, and so on. A good, solid patch review is typically 2-3 paragraphs or several bullet points. "+1" is NOT a great patch review comment.

Remember to make sure that your comment reflects any conversation that might've happened in Slack or other text chat, in a conversation over lunch, etc. If it's not in the issue queue, it never happened. :)

There are more tips on performing patch reviews at Reviewing patches, which is part of the larger Help in testing code part of the handbook.

Prerequisites

In order to participate in a patch review event, you'll need the following:

An inquisitive mind with an attention to detail. Extra bonus if you are one of those people with an uncanny ability to break things.
A development environment running a version of PHP appropriate for the version of Drupal you are using. An easy way to get this is to install a local Apache/MySQL/PHP package such as XAMPP. There are helpful videos for Windows, Mac, and Ubuntu Linux
Git. If you go to the command line and type in git --help you should see a bunch of text. If you do not, and instead see something like "Command not found," you need to download and install it.

Patch review commands

Note: The Version control tab always has the most up-to-date recommended instructions.

Download a copy of Drupal core from Git. You only need to do this once:

git clone --branch 9.0.x https://git.drupalcode.org/project/drupal.git

If you're reviewing issues from another project, you'll also need to install that module, theme, or distribution's git repository. You can find instructions for each project by navigating to the project page, and clicking the Version control link.
Find an issue that needs review from the "Drupal" project issue queue (or another project).
Give a quick read through the patch (even if you're a non-coder) and look for anything obviously wrong that sticks out to you.
If the code to review is in the form of a patch file, download the patch file to the "root" of your local Drupal installation (the folder with index.php in it). You can either do this with your browser or from the command line with a tool like wget:
```
cd /path/to/htdocs/drupal
wget http://drupal.org/files/issues/example.patch
```
[Need instructions here on what to do for issue branches, pull requests, etc.!]
Apply the patch, using Git:
```
git apply -v example.patch
```
See Troubleshooting 'git clone' if you receive errors during this step.
Install Drupal and enable any required contributed projects and themes.
Click around your Drupal interface and try and break the patch. Try and think of things that the original author may not have intended; for example, testing OpenID on a patch that affects the user registration form.
If you run into a bug, see if the same bug exists if you revert the patch:
```
git apply -R example.patch
```
Post your results to the issue, as described above in "Overview of reviewing".
Now, get back to a "clean" copy of Drupal and go back to step 2!
```
git reset --hard
```