How to contribute to Drupal 9 Porting Weekend

d9_porting_weekend_setup.md

How to prepare for Drupal 9 Porting Weekend

If you haven't heard about it, there is an important event scheduled for May 22 & 23, 2020 to do mass porting of Drupal 8 modules and themes to Drupal 9.

The following a set of instructions will show you how to contribute to that effort.

For a more detailed detailed account please see Kristen Pol's blog post, Preparing yourself for Drupal 9 porting weekend.

1. Install Drupal 8 + Helper Modules

1. First thing to do, of course, is to install Drupal 8 - the recommended way is to use composer. For alternative setups, see @mradcliffe comment below.

2. Second, install the Upgrade Status and the Drupal Rector modules.

2. Configuring Drupal Rector

Once the Drupal Rector module is installed you would need to provide a configuration file for it to scan your system properly. See the below instructions form the projects README section

You will need to have a rector.yml configuration in the root of your repository. This should sit beside your document root such as web or docroot. This project provides starting files that should handle most use cases. If your document root directory is web, you can copy the rector-config-web-dir.yml

cp vendor/palantirnet/drupal-rector/rector-config-web-dir.yml rector.yml

If your document root directory is docroot, you can copy the rector-config-docroot-dir.yml

cp vendor/palantirnet/drupal-rector/rector-config-docroot-dir.yml rector.yml

If your document root directory is something else you will need to manually copy and edit rector.yml.

NOTE: If you want to work with Drupal Contrib Themes, you will need to add - 'web/themes' under the autoload_paths: section in the rector.yml file. See a sample file here.

3. Finding a module/theme to contribute to

1. Pick a contrib module to support from the Drupal Deprecation Status page. Once you find something you want to contribute to, download that particular contrib module (make sure that it has the exact version as the one reported on that page).

2. Go to your local D8 site upgrade status page /admin/reports/upgrade-status. From the list of modules there, select the project you want to contribute to and scan it for an issues.

3. Once the scanning is done, there would be a report link on the right. You can see the report from the scan by clicking on that link. The report gives detailed instructions on how to fix the warnings/errors.

4. Use the Project's Issue Tracker

1. Go to the project's issues list page and look for issues tagged with Drupal 9 compatibility (the Drupal 9 readiness tag is outdated). If any of the issues you identified in the scan are available, please take a look at the each issue's comment thread to determine how you can help and also avoid redundant work.

2. If none of the issues you identified are not there in the issue queue, then create a new issue with the appropriate information. You will use this for submitting a patch once you're done fixing the issues.

5. Using Drupal Rector to fix issues

If the scan report shows that the module you have pick has errors you can fix automatically, then you can use Drupal Rector to do that.

Open your terminal to the root of your Drupal installation, run the following command to see a report of issues that can be fixed automatically:

vendor/bin/rector process web/DIR/contrib/NAME --dry-run

Be sure to replace DIR with modules if you are working with a module or themes if your working with a theme. Similarly, replace NAME by the name of the module or theme.

e.g for Bootstrap theme

vendor/bin/rector process web/themes/contrib/bootstrap --dry-run

WARNINGS

1. As of this writing, there is an empty test in the upgrade_status module that make the above command fail. To fix this, simply uncomment the Fatal Error text in web/modules/contrib/upgrade_status/tests/modules/upgrade_status_test_error/fatal.php. This is would probably be fixed by the time of the porting weekend.

2. If you have not set the themes path as part of the auto loader setting as shown in the Configuring Drupal Rector section above. Running the above command for themes will result in several errors, so be sure to add that entry in the rector.yml file.

Fixing issues with Rector

After identifying what Rector can fix with the --dry-run option, now it's time to actually fix the error by running

vendor/bin/rector process web/DIR/contrib/NAME

e.g. for Bootstrap

vendor/bin/rector process web/themes/contrib/bootstrap

This will actually make changes to files and you will be able to see the changes in git.

6. Manually Fixing Errors

Once Drupal Rector has fixed what it can automatically, it's your turn to make some changes manually.

Again the scan report at /admin/reports/upgrade-status is the best place to start. It has all the information you need on how to fix the errors/warnings, so please use that to start making the required changes.

You would need to rerun the upgrade status scan after each set of changes to make sure that they have been applied to the source code.

The last change you need to make is to update the .info.yml file of the project to indicate that it is now compatible with Drupal 9. In most cases all you need is to add the following:

core_version_requirement: ^8 || ^9

or even more a specific one based on the comment by @andypost below:

core_version_requirement: ^8.7.7 || ^9.0

For detailed explanation see the New core_version_requirement key page on d.o

7. Submit a patch in the Project's issue tracker

Once you're done with fixing the issues and updating the .info.yml file, it's time to submit a patch. Here is a detailed instruction on how to create a patch with Git.

Join Us for Porting Weekend

There is a whole lot that can go wrong while trying to contribute using the above instructions. This is where the Drupal Community comes in!!!

💙💙 💙 THE DRUPAL SLACK CHANNEL #d9readiness 💙💙💙

*** >>> GET YOUR SLACK INVITATION <<< ***

First thing to do, of course, is to install Drupal 8 - the recommended way is to use composer.

Note, this is more complicated than what is written.

1. When working with Drupal sites, composer is the recommended way to install Drupal 8 or above.
2. Novice contributors are encouraged to use quicksprint to get up-and-running faster at contribution events mainly because it allows us to also work with Drupal core and not only contributed modules. If a module does not require non-Drupal dependencies, then this is probably still the recommended way of doing things so as to stay consistent.
3. Experience contributors are encouraged to use the local environment and work flow they are comfortable with:
   • For core development, that will mean cloning Drupal from git
   • For contrib development, probably following #1 above.

Thanks @mradcliffe, it is certainly helpful to make the distinction. Added link to you comment.

Better use core_version_requirement: ^8.7.7 || ^9.0 because this key was added exactly in this version
But when you replace deprecated functions like entity_get_display() make sure to point ^8.8 || ^9.0

Thanks @andypost, I have made the adjustment and added a link to your comment.

While running Drupal Rector or Upgrade Status if you get similar warning to the one below:

Class PHPUnit\Framework\TestCase not found and could not be autoloaded.

Make sure that that you've installed drupal/core-dev.

Note: If you have installed drush before this, then you would be unable to install drupal/core-dev.

Steps to follow:

1. Remove drush,

composer remove drush/drush

2. Install drupal/code-dev

composer require drupal/core-dev

3. Install drush back again

composer require drush/drush