Preparing Drupal.org projects for Drupal 9

There are various tools to ensure Drupal 9 compatibility of a project. This section is about the process to follow.

Keep supported core branches in mind

Drupal core has a year of support for core branches. For example, when Drupal 8.8.0 was released, Drupal 8.6.0 became unsupported and support for 8.7.0 continued. Support for Drupal 8.7.0 will only end once 8.9.0 is released on June 3, 2020. This means that even though the tools may be reporting that something is deprecated, it may not be actionable because it would mean dropping support for an otherwise supported core branch. This could get painful for users of your project - if you need to release an important fix it could force the user to update core even though their version is still supported. Keep this in mind when working on removing deprecated code. Testing system support for this is being discussed in Support deprecation testing for multiple branches on contributed modules on Drupal.org.

If you are using code that was only deprecated in 8.8.x and above, wish to continue supporting 8.7.x while being ready for Drupal 9 at the same time, you can sometimes achieve this with a little extra work. For example, if your code calls entity_get_form_display(), you can do something like this:

  protected function getFormDisplay($entity_type_id, $bundle_id, $form_mode) {
    if (floatval(\Drupal::VERSION) >= 8.8) {
      return \Drupal::service('entity_display.repository')
        ->getFormDisplay($entity_type_id, $bundle_id, $form_mode);
    }
    // This is fallback code for 8.7.x and below. It's not called on later
    // versions, so we don't nee to "fix" it for upgrade_status.
    /** @noRector \DrupalRector\Rector\Deprecation\EntityGetFormDisplayRector */
    // @phpstan-ignore-next-line
    return entity_get_form_display($entity_type_id, $bundle_id, $form_mode);
  }

The @noRector and @phpstan-ignore-next-line comments tell the automated tools that search for deprecated code to ignore the line. Since it's only fallback code for 8.7.x, it's not preventing anything from working on Drupal 9 and above, and shouldn't be flagged as a warning or error by tools like Upgrade Status, drupal-check, Upgrade Rector and drupal-rector. These markers are also useful to find and remove fallback code in the future once you don't need it, so it's not accidentally left around. Note that the @noRector comment must be enclosed in /** */ comments for it to work. It must also include the fully qualified class name of the rector deprecation you want it to ignore. Also note that the @phpstan-ignore-next-line comment should be immediately before the line to ignore, so it should come after the @noRector comment.

When should I create a Drupal 9 branch of my project?

Never! Some releases of project are likely to be compatible with versions of Drupal 8, 9, and later, simultaneously. There is no longer a need to maintain different branches of your project for each major version of Drupal core. You can keep making releases with 8.x-* versions.

Drupal 8.7.7 onwards supports a new core_version_requirement key in info.yml files where you can declare your project compatible with both Drupal 8 and 9 at the same time.

Drupal 8.8.3 onwards support semantic versioning for contributed projects. Once your project supports only Drupal 8.8.3 and later, and you are ready to make a new major branch, you can switch to semantic versioning.

Guiding contributors to help you make the move

Edit your project and find the "Drupal 9 plan" field on the editing form. Inform users about your plans for your Drupal 9 process using that field. The entered text will appear on the project page. There are some suggested text snippets for projects that need funding or suggest replacements.

The contributor guide has some excellent tips at Help contributed modules prepare for Drupal 9 to help guide your contributors help you best. Send that page to contributors with information on your preferred approach to the process (eg. how to split fixing various deprecations into issues) so that contributors can be most effective in helping you.