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
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.
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
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).
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.
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
Go to the project's issues list page and look for issues tagged with
Drupal 9 compatibility(the
Drupal 9 readinesstag 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.
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
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
As of this writing, there is an empty test in the
upgrade_statusmodule that make the above command fail. To fix this, simply uncomment the
Fatal Errortext 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.
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
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!!!
Note, this is more complicated than what is written.