Preparing yourself for Drupal 9 porting weekend

Submitted by kristen on Mon, 05/18/2020 - 01:12

As you may have heard, Drupal 9 porting day a couple weeks ago was a huge success! Gábor Hojtsy wrote up a great summary on the event including all the money that was raised for the Drupal Association. And, you can read my porting day recap as well. Thanks again to all who helped out.

The April porting day was so successful that Surabhi Gokte and Gabriele Maira (gambry) encouraged Gábor to organize a repeat performance and, like magic, we have Drupal 9 porting weekend coming May 22 and 23. This is scheduled during the time we had hoped to contribute at DrupalCon Minneapolis. Now we'll join each other virtually in a few days to make Drupal even better.

The goal for Drupal 9 porting weekend is to make more Drupal 8 contributed projects (modules, themes, and distributions) compatible with Drupal 9. As of May 16, 2020, there are 1,617 out of 8,982 projects that already work on Drupal 9. So, during the porting weekend, we'll work on the 7,365 that don't. While that might seem like a daunting number, about half of those (3,405) likely only need a one-line change to make the project Drupal 9 compatible!

There is a wonderful effort underway right now to automate Drupal 9 compatibility issue and patch creation for contributed projects. Even with this effort, we still need your help during porting weekend. We hope you can participate!

Image credit: Aaron Deutsch

I've listed some useful Drupal 9 porting resources you can review and information about collaborating in Slack during the event. I've also added specific sections for preparation depending on the type of contribution you are hoping to do:

I don't have time to prepare
I'd just like to watch
I'd like to mentor others
I'd like to find and create issues
I'd like to create and update patches
I'd like to review patches
I'd like to test patches

Resources

There are a lot of Drupal 9 resources, but here are some that are particularly helpful for preparing for patch weekend:

Collaborating via Slack

We'll be collaborating in the Drupal 9 readiness (#d9readiness) channel on Slack. If you don’t have access to Drupal Slack click here to get an invite.

When you are ready to join the porting weekend, announce yourself in the Slack channel with something like "I'm here to contribute and will be helping for the next X hours. [insert what you are hoping to do or if you need help here]", e.g.

I will be working on my personal Foobar module and don't need any help but will post status updates here.
I will be working on my personal Foobar module and would like help reviewing/testing.
I will be finding my own issues to work on and will post them here as I work on them so others can collaborate.
I don't have an issue I'm working on but am open to creating patches.
I don't have an issue I'm working on but am open to reviewing/testing patches.
I'm not sure what to help with and need guidance.

We will be using Slack threads extensively during porting weekend. Each project or issue that is being worked on should ideally have a Slack thread associated with it in the channel. Also, if you are responding to questions in the channel, please respond via a thread unless the answer is a simple yes/no type response that won't have other people chiming in. It's best to err on the side of creating threads in order to keep the "chatter" organized so that it's easier for people to understand what's happening and being worked on.

There will be mentors available to help match people with projects and issues. The mentors are listed on the Drupal 9 porting weekend event page. If you have questions, please do not send direct messages to the mentors unless there is a Drupal Code of Conduct issue that you need help with. You can send questions directly in the #d9readiness channel. You don't have to be a mentor to answer questions. If you know the answer and have time to respond, please do so.

I don't have time to prepare

Do you want to help out during porting weekend but don't want to think about it until then?

No worries! Show up in the #d9readiness Slack channel and announce your arrival along with what you'd like to help with. If you don't know how to help, that's okay too. The mentors can find something for you. :)

I'd just like to watch

Do you like the idea of helping but haven't done it before and you're not sure you'd like to participate?

No pressure! Join the #d9readiness Slack channel and watch in real time as people contribute together. It's okay to just hang out and see how it happens. You won't be forced to do anything but, who knows, maybe you'll change your mind and jump in after all. :)

Note: If you are interested in livestreaming the event on Twitch.tv or similar, let us know via the Slack channel. Thanks to Ofer Shaal for this great idea!

I'd like to mentor others

Have you prepared any websites or contributed projects for Drupal 9 already? Or helped with Drupal 9 compatibility issues in the issue queues?

Nice! We could use your guidance. If you are up for mentoring at this event, contact Gábor Hojtsy and let him know what days and times (with time zone) you can cover. Even if you can only help for an hour or two, that's okay! Ideally, we'd love to get 1 to 2 people covering all times across all time zones over the 2 days. You can check the current coverage on the Drupal 9 porting weekend event page.

After you sign up, make sure to join the #d9readiness Slack channel and arrive during your planned time. If there are other mentors there already, check in with them to see if they need any help with anything. Otherwise, scroll backwards in the Slack channel to catch up on what's been happening and if anyone has asked for help and didn't get a response.

How you mentor others will depend on what they need help with. Someone might need help finding an issue or project to work on. Another might have a technical question when reviewing a patch. If you are worried you might not know how to answer all the questions, it's okay! If you don't know the answer, just let them know and, if possible, see if someone else in the channel knows the answer. This is how we learn together.

If time allows, we hope to have an up-to-date list of issues to start with at the beginning. Stay tuned in the Slack channel for more information about this.

I'd like to find and create issues

Are you good at searching the issue queues?

Searching the issue queues for existing issues is a very valuable skill that should not be underrated. Sometimes we might forget to check if there is already an issue for our Drupal 9 compatibility problem and create a new one and we end up with duplicates. It happens to the best of us. I've done it myself!

Maybe you aren't up for doing any issue patching, reviewing, or testing but would be happy to look for existing issues or see if issues are duplicates and close out the extras. We'd love that type of help! If you would like to focus on this aspect of contribution, here are some tips:

Check the Drupal 9 plan of the project

A thousand projects set their Drupal 9 plans up for their project pages. Project maintainers can do this by editing their project manually. If a Drupal 9 plan is provided, and it does not say the project is Drupal 9 compatible already, it would be the best starting point for finding the related issues. There still may be other issues that need triage though.

Searching the issue queues

If there was no Drupal 9 plan or even if there was a Drupal 9 plan, looking for other issues may turn up things you can clean up. You'll want to use the "Advanced search" when searching the queue and make sure to look for all issues rather than just open issues. I've made the mistake before where I was only looking at open issues and missed ones that were fixed but closed.

Keep in mind that some issues are tagged with "Drupal 9 compatibility" but not all are. In some cases, issues won't be tagged at all. There is an old tag called "Drupal 9 readiness" that was mistakenly used. If you find relevant issues that aren't tagged with "Drupal 9 compatibility", you can add the tag as you come across them. Only remove the "Drupal 9 readiness" tag if the issue is tagged with "Drupal 9 compatibility".

The issue titles aren't consistent so you'll need to search for various keywords within a project's issue queue, e.g. "drupal 9", "compatibility", "deprecated", "deprecation", "port", "update", "readiness", "core_version_requirement". Searching for these types of keywords using the "Advanced search" should help you find most, if not all, relevant issues.

If you need a refresher on the issue status codes, the "Status settings of issues" documentation is helpful. For the porting weekend, it would be good to work on issues with "Active", "Needs work", and "Needs review" statuses. You can also double check that the "Reviewed & tested by the community" (RTBC) issues were actually reviewed and tested by someone before moving to the RTBC status. The person adding the patch should not set the issue status to RTBC themselves.

What do these issues look like?

It's good to be familiar with what these Drupal 9 compatibility issues typically look like. Here are some examples with their current status as of May 16, 2020:

Info.yml file core_version_requirement changes
- Active: Add Drupal 9 into the require section of composer.json
- Needs work: Add the 'core_version_requirement' key in info.yml
- Needs review: core_version_requirement does not list Drupal 9
- RTBC: Add missing core_version_requirement key to info files
- Fixed: Make core_version_requirement consistent in all info files
- Closed (fixed): Add core_version_requirement for Drupal 9 compatibility
- Closed (fixed) [no patch]: Add the 'core_version_requirement' key in info.yml and composer.json files
- Closed (duplicate): Add new key core_version_requirement in ctools.info.yml
- Closed (duplicate) [Merged with another]: Add new key core_version_requirement in pathauto.info.yml
Deprecations
- Active: [Meta] Drupal 9 Deprecated Code Report
- Needs work: Drupal 9 Deprecated Code Report
- Needs review: Make the code compatible with Drupal 9
- RTBC: Fix deprecations including jQuery UI dependency and info.yml update
- Fixed: [Drupal 8.8.x] Replace use of deprecated file functions
- Closed (fixed): Drupal 9 readiness
- Closed (duplicate): Drupal 9 Deprecated Code Report
Miscellaneous
- Active: Create new Drupal 9 compatible release and update project page with Drupal 9 info
- Needs work: README.md does not follow best practices
- Needs review: Read me file missing
- RTBC: All dependencies must be prefixed
- Fixed: Rename D8 Editor Advanced link module
- Closed (fixed): Add drupalci.yml to test for deprecations
- Closed (duplicate): webform_submission_log sub-module port to phpunit

What issues can be closed?

It's important to only close issues if you know they are duplicates or are irrelevant. If you find more than one issue where they are for the same thing (e.g. updating the info.yml file), then you'll have to assess which, if any, should be closed. This is a judgment call that's handled on a case-by-case basis.

Example 1: Both issue 1 and issue 2 are for info.yml file changes. Neither have had any work on them or any comments. In this case, I'd keep the first issue and close the second as a duplicate and specify the first issue in the "related issue" field on the second issue.

Example 2: Issue 2 had work done on it and has a patch and issue 1 doesn't have any work done yet. In this case, I'd keep the second issue and close the first and specify the first one in the "related issue" field of the second issue.

Example 3: Both issue 1 and issue 2 have had work done. This one is trickier. If it's obvious who did the work first, I'd close out the later issue and add the "related issue" to the other one. If it's not obvious which should be closed, I'd add a comment to both issues and set both of them up to be related to each other.

Example 4: This is a scenario that happened to me recently. Issue 1 was for the info.yml file and issue 2 was for dealing with the jQuery library dependency. Issue 1 had a patch and was RTBC. Issue 2 eventually added the info.yml file fix into the patch for the jQuery dependency changes. This made issue 1 a duplicate so it was closed. The person who did the patch for issue 1 was given an issue credit on issue 2 even though they didn't work directly on that issue. (Issue credits can only be assigned by project maintainers, so when working on issues of projects you don't maintain, please leave a note suggesting to add the appropriate credit for the issues you closed).

When should issues be created?

If it's clear from searching the project's issue queues that there are no existing issues for Drupal 9 compatibility, the next step is to double check using the Upgrade Status module. This can be done using simplytest.me or your local machine.

If it's a module, you would enable the module you want to check and enable the Upgrade Status module. Then you would check the Upgrade Status page for the module's Drupal 9 compatibility info. Ideally, you would check the module's most recent release as well as the module's dev version. This is because it's pretty common for compatibility fixes to be in the dev version but not in an official release yet.

It is useful to have the dreditor Chrome browser plugin when creating issues so that you can follow the issue formatting guidelines. But, don't let this keep you from creating issues. You can look at this issue example for formatting.

Please tag all Drupal 9 compatibility issues with the tag "Drupal 9 compatibility" and, if you are working on it during the porting weekend also tag it with "Drupal 9 porting weekend". Please do not tag it with outdated tags like:

~~"D9 readiness"~~,
~~"Drupal 9 readiness"~~,
~~"Drupal 9"~~,
~~"D9 update"~~,

or create new tags. It is difficult to find issues when lots of different tags are used. Other tags that may be relevant to add are "Novice", "Needs tests", "Needs manual testing", "Needs reroll", and "Needs issue summary update".

I'd like to create and update patches

Are you a developer interested in creating or updating code patches?

For some projects there are already patches ready for review and testing but, for others, new patches need to be created manually or using the drupal-rector utility or the Upgrade Rector module.

Note: It is very important to check the issue queue first to make sure you are not creating duplicate patches.

Using a local development environment

To create and update code patches locally, you have a number of options. I'm agnostic on local development tools and have used LAMP, MAMP, MAMP PRO, Lando, and DDEV at one time or another. I've known others who've successfully used Docksal and WAMP.

Pick your favorite or try something new. If you want to be more efficient during the porting weekend, I highly recommend you set up your local environment a few days beforehand. You'll want to make sure you know how to "blow away" your testing site easily and recreate it.

Generating patch files

If you are new to creating patches for Drupal projects, I highly recommend scanning the Advanced patch contributor guide. Since I don't create patches regularly, this is where I go to refresh my memory every time I make one.

For additional information for creating patches manually or using Drupal Rector, Tsegaselassie Tadesse (tsega) wrote a great post for the event: "How to prepare for Drupal 9 Porting Weekend".

I'd like to review patches

Are you a developer who understands Drupal coding standards and has an eye for detail?

For every patch that gets committed, it's best practice for someone who didn't write the patch to review the code. Code patches might be simple, one-line changes or complex changes that span many files.

The patches we are focused on for the porting weekend will be mostly deprecation patches and info.yml file patches. Sometimes these are combined into one issue and sometimes they are split out. You can review some example issues above. For the info.yml file patches, these are trivial to code review. Ideally, someone should test the patch as well before marking these issues RTBC.

For reviewing deprecation patches, you'll likely need to check the change record for the deprecation to see if the code is updated properly. Some of these are pretty straight forward such as replacing drupal_set_message with the Messenger service while some will be more involved like handling the removal of jQuery UI from Drupal core.

If the changes look good and you have time to successfully test the patch as well, the issue can be marked RTBC. If you review it but don't test it, add a comment with your notes and make it clear that it still needs manual testing and add the "Needs manual testing" tag. If the patch needs changes, add your comment with feedback and move the issue back to "Needs work".

When doing code reviews, it's very useful to use the dreditor Chrome browser plugin". This will provide a UI for reviewing the code as well as some shortcuts when editing your comment.

I'd like to test patches

Do you like testing things?

Manual testing is a vital part of fixing issues. For each project that's made Drupal 9 compatible, we need people to try out the updates to make sure they don't break anything. How you test depends on the project. Some will be easy to test and some won't be. Ideally, you'll need to be familiar with the contributed project features to test properly though, for simpler projects, looking through the project page and README file might be enough to get you going.

Testing using simplytest.me

In many cases, you can test using simplytest.me. If you haven't used this wonderful tool, you've been missing out! There are times when I don't want to install a site locally but want to contribute by testing a patch. This is very common for me right now because my laptop is almost out of disk space. ;) But, it could be that you are on a computer that doesn't have a development environment set up or you just don't want to set one up for whatever reason.

If you'll be using simplytest.me, I highly recommend installing the dreditor Chrome browser plugin so that when you see patches in the issue queue, you'll see a SIMPLYTEST.ME button. Click that and it will open a new tab with the relevant project and patch. You don't have to install the plugin though; you can go directly to simplytest.me and choose the project and add the link to the patch.

Note, at the time of writing, simplytest.me is working for testing Drupal 8 versions but not Drupal 9. For contributed projects that are sticking with a Drupal 8 version and making that version Drupal 9 compatible, then you can test the Drupal 8 version on simplytest.me. For projects that are making a Drupal 9 version, then you'll need to test locally. If you are able to help with updating simplytest.me for Drupal 9 support, please contact Adam Bergstein (@nerdstein) in the #simplytestme Slack channel.

Side note: When testing core patches, something to double check is that you are testing the correct version. The version selected automatically on simplytest.me is the same as the version on the issue. This isn't always the version for the patch you are testing. This is not a problem with contributed project issues as long as the version on the issue is correct.

Testing with a local development environment

If you want to test locally, you have a number of local development options. One advantage of local testing compared to simplytest.me is that it's usually faster to spin up and refresh your site in between testing different patches. With local testing, you can also test what happens when you are on an older version of the project and update the code with composer.

Reporting your results

As you manually test a project's features, it's good to take screenshots of key things as you go so that you can upload a select number in your comment. You don't have to take tons of screenshots, but you especially want to screenshot any bugs you find during testing and also copy any error text you encounter.

When you are done testing, it is very helpful to explain your steps in a bulleted list. For example, here's a Smart Trim issue comment I added with steps to reproduce and screenshots. Bonus points if you add the testing instructions to the issue summary so it's easier for others (and yourself!) to find it later.

Please add information about your testing to your issue comment instead of a "works for me" type comment. It is much more helpful to know what you tested, if it worked as expected or not, error text if available, and select screenshots showing it working or not working.

Thanks!

Big thanks to Gábor Hojtsy and Ofer Shaal for reviewing and fine-tuning this post. It takes a village to make Drupal its best! We hope you join us for Drupal 9 porting weekend, no matter how you'd like to participate.