Using Lando for Drupal 8 Core Issue Patch Testing

Drupal thrives with love and care from the community. We help move the Drupal project forward by mentoring, sharing knowledge, helping with drupal.org (d.o) issues, and more. If you want to help in the d.o issue queues, you are very welcome! While there are many ways to help, one important piece is reviewing and testing code patches.

Finding a Drupal Core Issue Patch

You do not need to know how to code to test patches. That is important to understand. As long as you reproduce the problem in the issue summary, then you can test a patch when it's ready to be tested. You will know when an issue's patch can be tested when it's been marked "Needs review". If you are not able to review the patch code itself, but can reproduce the issue, please test the patch. Someone else can always do the code review part.

Prior to testing the patch, check to see if anyone else has already tested it. If so, it's best to move on and find another patch that "Needs review" and has not been tested yet. When you find a good issue, you'll need to reproduce the issue without the patch. Then, with the patch applied, go through the steps again to see if the patch did indeed fix the issue.

If you are new to working in the d.o issue queue (or have a limited time to review), a good way to find a patch is to look for the "Novice" tag in the advanced search. But, if you are new to Drupal contributions and go to the drupal.org home page, it's not easy to see how to even find issues.

 

Here's how you navigate to the Drupal core issue queue search manually:

1. Go to drupal.org
2. Login or create an account if you don't have one
3. From the home page, click "Get the code"
4. Click "Drupal's project page"
5. Click "Advanced search" under the "Issues for Drupal core" title

 

Now you can search for "Novice" or other tags that are of interest to you. For example, if you'd like to help with accessibility or multilingual issues, there are tags for that. When you are first starting though, I recommend finding a "Novice" issue. In addition, you'll want to find one that is in the "Needs review" state.

Read through the issue summaries until you find one that you understand and want to test. Keep in mind, in some cases, the issue may not be easy to test manually. Try to find one that is. If there were older patches, you might find that they were tested so that will give you an idea what needs to be tested for the new patch.

 

Example Patch

I went through and found an issue with a patch that was in "Needs review" state and tagged "Novice" and seemed relatively straightforward to test. Here's my issue:

https://www.drupal.org/project/drupal/issues/1521996

 

I found that no one had code reviewed or tested the most recent patch so it was a good candidate to test. I assigned the ticket to myself so that I can test it and let others know I'm working on it. Note that I could test this patch with simplytest.me easily enough. If I were going to do that, I'd click the "SIMPLYTEST.ME" button next to the patch which launches the Drupal site installation process on simplytest.me. I have that "SIMPLYTEST.ME" button when viewing d.o issues because I have dreditor installed for Chrome.

 

Remote vs Local Testing

When testing issue patches on drupal.org, you can test using simplytest.me as mentioned above or via your local development environment. Simplytest.me is good when you don't need the site later (simplytest.me sites only exist for 12 hours) and there are a limited number of patches to apply (no more than 3). It is an awesome tool so use it when you can.

 

When simplytest.me does not make sense for patch testing, then you should use your local environment. This could be LAMP, MAMP, WAMP, LEMP, etc. depending on your machine and whether you want to run the Drupal site in a container or not. I'm on a Mac and previously only used MAMP Pro for local development but have been switching over to Lando in recent months.

 

Installing Lando

Before you use Lando, you need to install it. Rather than bore you with the details here, check out Lando's awesome documentation for installation instructions. One important note is that Lando will install Docker. And, if you are on Mac, you'll need to be on a "not too old" OS version in order to get a more recent version of Docker.

You can use Lando for lots of projects in addition to Drupal (e.g. WordPress and Laravel). On the Lando documentation site, look at the left side for all of the Lando "recipes". One of my favorite recipes is the Pantheon one because it makes working with Pantheon sites even better. For example, it sets up Solr by default so that you can easily do local Drupal Solr development without any extra configuration. Nice!

Some Lando Goodies

Lando bakes in a lot of nice things for you. If you use drush, there is "lando drush <command>" which is essential. If you want to install new modules, composer is already set up so you can do "lando composer <command>". At first it takes a some time to remember to prefix things with "lando" but after awhile it's pretty automatic. Or, you can create some bash aliases like ldrush or ldr to lessen the typing. Running "lando -h" will list the commands but here are a few favorites:

• lando start
• lando drush cr
• lando drush cim
• lando drush cex
• lando drush updb
• lando drush uli
• lando composer update
• lando logs

Testing with Lando

At this point, you are probably wondering if we are ever going to test the patch. So... let's do it!

Remember, you need to have Lando (and Docker) installed first. You will also need git installed.

Step 1: Create Vanilla Drupal Site

I picked a Drupal 8 patch to test so I will need to install Drupal 8. But, I want to install it from the Drupal core repository so the steps are a bit different than the Lando Drupal 8 documentation page. Here's a summary of what I would do on my Mac:

1. Create a directory (on the command line)

   1. cd <directory where I want to put the site>, e.g. cd ~/Sites
   2. mkdir <new directory>, e.g. mkdir drupal8test
   3. cd <new directory>, e.g. cd drupal8test

2. Find the Drupal core code (in the browser)

   1. Go to https://www.drupal.org/project/drupal/git-instructions
   2. Choose the version you want (important: this should match the issue you will test, e.g. 8.6.x)
   3. Click "Show" button
   4. This will show you the git clone command to use
   5. After you understand this step, you can skip it in the future by manually putting in the branch you need for the patch (see next step)

3. Get the core code and initialize Lando (on the command line)

   1. Run the git clone from above but add a " ." (space and period) at the end so it ends up in your new directory and not a subdirectory
      1. git clone --branch <branch> https://git.drupal.org/project/drupal.git .
      2. e.g. git clone --branch 8.6.x https://git.drupal.org/project/drupal.git .
   2. lando init
      1. recipe = drupal8
      2. webroot = .
      3. name = Drupal 8 Test
   3. lando start
   4. lando composer install
      1. Note that if this does not work, run "lando restart" and then try again
   5. lando info
      1. This will provide the URL for your site, e.g. https://drupal-8-test.lndo.site

4. Install the Drupal site (in the browser)

   1. Go to the site, e.g. https://drupal-8-test.lndo.site
      • Because this is https, on Chrome, you might see a "Your connection is not private" page
      • You can click to open the ADVANCED section and then click the "Proceed to drupal-8-test.lndo.site (unsafe)" link 
   2. This should redirect you to the install page, e.g. https://drupal-8-test.lndo.site/core/install.php
   3. Go through the regular installation process
      1. Important: database info can be found using "lando info"
         1. Database name, username, and password, e.g. drupal8, drupal8, drupal8
         2. Host and port should be the internal host and port, e.g. database, 3306
         3. Note your username, password, email address

If all goes well, you'll have a brand new vanilla Drupal 8 site.

Step 2: Run Drupal-y Things

Let's save our config in case it changes later. We'll run these with drush so make sure drush is working:

1. lando drush status
2. If it's not working, run: lando composer require drush/drush

 

Now run "lando drush cex" and it will save the config into the sync directory.

Step 3: Reproduce the Issue

Now you have a vanilla Drupal site to test on so it's time to reproduce the issue.

1. Read the issue summary
2. Follow instructions for reproducing the issue
   • Note that sometimes the steps to reproduce will be in the comments instead of the issue summary. If you find this to be the case, copy/paste the instructions into the issue summary so they are easier to find
3. If you cannot reproduce the issue, then you should add a comment to the issue saying so and put the steps you followed
   • Screenshots of the discrepancy are good to include in this case
4. If you can reproduce the issue, that's great
   • If no one has created screenshots of the issue, create them so they can be uploaded to the issue

For my issue, I need to test the message shown when trying to reset password so I went to a new browser where I was not logged in and tried it. I was able to reproduce the problem.

Step 4: Apply the Patch

Now we need to apply the patch from the issue. Drupal.org has git patch documentation with more instructions but here is one approach on a Mac.

1. In the browser
   1. Go to the issue
   2. For the most recent patch, right click on the link and click "Copy Link Address"
2. On the command line
   1. cd <your directory>, e.g. cd ~/Sites/drupal8test
   2. wget <patch url>, e.g. wget https://www.drupal.org/files/issues/1521996-120.patch
      1. You'll obviously need wget installed for this to work
      2. Alternatively you can use curl
   3. patch -p1 < <patch file>, e.g. patch -p1 < 1521996-120.patch
      1. You can use git commands as well (documented in the Drupal.org patch documentation)
   4. If the patch "applies cleanly", then you won't see any errors
   5. If the patch does not "apply cleanly", you may be in the wrong directory (make sure you are in the top level web root)

In my case, the patch applied cleanly.

 

Step 5: Run Drupal-y Things

Some patches require that we run config imports or database updates so it's best practice to run these just in case. Run these drush commands to make sure the site is updated:

1. lando drush updb
2. lando drush cim
3. lando drush cr

Step 6: Test Again

Now it's time to see if the patch did what we expected. Run through the steps to reproduce the problem and take screenshots where appropriate.

The first time I ran through testing, it didn't do what I expected. If that happens to you, that's ok. That is still useful information and should be reported. I tested again (with the patch applied when installing the site) and then it did work.

 

 

Step 7: Report your Findings

Add a new comment including:

1. How you tested
2. Did it work or not
3. Screenshots (just enough to be useful)
4. Unassign the issue from yourself, if necessary
5. Change the state
   1. If it passed manual testing but still needs a code review, leave the state as "Needs review"
   2. If it did not pass manual testing, change the state to "Needs work"
   3. If it passed manual testing and you did a code review and it passed that, add all your notes and mark "Reviewed & tested by the community" (aka RTBC)

Step 8: Keep your Lando Environment (optional)

Now that you have a Lando environment, if you want to do more patch testing, you can keep the one you created already. You will need to get rid of any old patches and update the git repo from before testing new patches. You might also need to reinstall the site with a fresh db if you are testing similar things and old patches affected the database.

1. Revert your code and get latest (on the command line or via your favorite git tool), e.g.
   1. git reset --hard HEAD
   2. git pull
2. Wipe out database to reinstall (on command line)
   1. lando mysql
   2. drop database <database name>;
      1. e.g. drop database drupal8;
   3. quit
   4. Reinstall the site with the process above (starting at "Install the Drupal site")

Hope to see you in the issue queue!

Epilogue: While the above steps are focused on Drupal core issue patch testing, the steps are pretty similar if you are doing Drupal "contrib" (module, theme, or distribution) issue patch testing. And, Lando can certainly help if you want to review code patches and maintain code in contributed modules, themes, and distributions. Looks like some follow-up blog posts are in order. :)