Drupal's adoption of GitLab lead to five times faster test runtimes but for this post I will look at how it makes it much easier to update modules to a new major version. It is now possible to fully use the user interface of drupal.org and drupal.org's GitLab features to make modules compatible and even make new releases available. I'll use one of my modules as an example: Upgrade Rector. Let's walk through what I did.
Check the Project Update Bot
Originally built by Ted Bowman at Acquia, recently faithfully maintained by Björn Brala at Swis, the Project Update Bot is a fantastic tool! I posted details about the technology behind it on the Acquia Dev Blog, but the gist is that it runs Upgrade Status to establish a readiness baseline for modules. Then it runs Drupal Rector on them to fix as much automatically fixable issues as possible. Then runs Upgrade Status again to see if anything was left. If there was no issues left, it also updates the info.yml and composer.json files. Björn updated the bot recently for Drupal 11 to open GitLab merge requests given patch testing going away very soon.
The bot opened more than 6000 issues with the ProjectUpdateBotD11 tag across all projects. As of this writing, 4755 of those projects only need an info.yml and if needed a composer file change. Those modules could very well use the process I explain here to make their codebase compatible without leaving the browser.
For my sample project, the respective issue is Automated Drupal 11 compatibility fixes for upgrade_rector.
Best to have tests
My module has tests which makes me able to do everything at once, without waiting for further human reviews. The green checkmark indicates on the issue that the tests ran fine with the merge request opened by Project Update Bot.
If I would not have tests or did not trust my test coverage, human review/testing would be needed outside Drupal.org, but all of the steps I do here would still apply. (In a followup blog post I plan to explain how I use DrupalPod (based on GitPod) to do human testing in such cases).
Testing on Drupal 11
The one thing we would still need that this does not do is to prove that the changes also pass on Drupal 11. For that to be tested, we need to add one more line to the merge request. Don't worry, we are using the UI only still!
First I need push access to this branch which the green "Get push access" button grants me. Once pressed, it turns into a checkmark saying "You have push access" very quickly. Drupal.org uses collaborative forks so that more people can work on the same change proposal.
If I would have expected more bot results, I should have created my own branch (also possible on the GitLab UI) to keep the bot branch clean. I was very confident that this will be good, so I clicked directly into the project-update-bot-only branch (first link in the row that has the merge request).
My module is already tested on the previous and current major version for compatibility. It was not compatible with Drupal 11 before, so testing on that was not enabled. GitLab CI provides variables for this to be configured. This is what the .gitlab-ci.yml file looked like in the merge request to test against Drupal 9 and 10:
#
# DrupalCI includes.
#
include:
- project: $_GITLAB_TEMPLATES_REPO
ref: $_GITLAB_TEMPLATES_REF
file:
- '/includes/include.drupalci.main.yml'
- '/includes/include.drupalci.variables.yml'
- '/includes/include.drupalci.workflows.yml'
#
# Start custom overrides.
#
variables:
OPT_IN_TEST_CURRENT: 1
OPT_IN_TEST_PREVIOUS_MAJOR: 1
The only thing we need to add to this is yet another variable to test with the next major: OPT_IN_TEST_NEXT_MAJOR: 1. We can use either editor offered on the user interface for this. When I need to edit multiple files to achieve a fix, I usually use the Web IDE (in-browser VSCode) provided by GitLab, which has great changeset review before commits.
For this case, the pipeline editor is best. That is a text editor by default but also does inline validation of the syntax and other goodies such as visualization that makes it better than editing locally actually. Once I added that one line, it tells me the syntax is still valid, so I went ahead to commit the change directly here to the branch (which the merge request is based on).
Next step was to wait a bit for the pipelines to complete (in other words, the tests to run). Going back to the issue, the MR's row still links to the now updated pipeline results, which show that the next major test does not pass yet (see yellow exclamation mark by the "phpunit (next major)"):
Clicking into those test results showed that my test module's info file was not yet compatible with Drupal 11. That should not even have a core_version_requirement specified, so I went in and edited on the GitLab UI again. Made a commit to the branch and awaited test results.
This quickly came back all green on both current, previous and next major version PHPUnit tests. Purists may recognize there are cspell errors (on words like rectorable used in the code) and stylelint issues, among others. Those could also be fixed later, but they don't have any consequence for Drupal 11 compatibility.
Good enough, merge it in!
Now that I have tests passing on all tested versions, time to merge the fix in! Went back to the issue and scrolled down to the bottom. Made sure the credits are properly specified. The UI for merging in the changes is there as well. This will set the proper commit message and squash the branch commits to one commit as specified in the merge request.
That finished quickly and replaced itself with Merged !9 🎉. I set the issue to fixed and saved it. You may want to keep it open if you expect the bot may come up with more fixes. (In that case, I suggest you don't make human commits in the bot branch either, but you can also use the GitLab UI to create a new branch off of that one and open a new MR for your manual changes).
Make a tagged version available
So now my 2.x development branch is Drupal 11 compatible, but how do I make a tagged version? Of course using the user interface! Like all drupal.org project pages, my module's project page has a Source code link at the bottom of the sidebar. That links to https://git.drupalcode.org/project/upgrade_rector which is the main GitLab user interface for my module.
The Code > Tags page lists all existing tags, and provides a blue New tag button at the top. This form allows me to tag my new release on the 2.x branch. The next logical version for this is 2.0.0-alpha3 (last I had alpha2 a few months ago and I did not make any significant change here).
Once I saved this form, the tag was immediately available and pipelines were starting to run right away for this tagged release.
Finally, create the drupal.org release
The drupal.org release for this tag will make the release available on the composer endpoint and the project page as well as make it possible to submit issues against the release. It also lets me explain what changed in this version and who contributed.
For this, I went back to the project page, which has an Add new release link at the bottom below the "Releases" section. This offers me a list of all git tags that do not have a release associated yet. My tag was the only one listed there as expected.
While not mandatory, I like nice release notes for new versions. We should celebrate contributors and their achievements! In this case it was only me and the bot, but I followed my usual process anyway. I use Matt Glaman's excellent https://drupal-mrn.dev/ which allows me to generate release notes for any project release. I specified my project name, the previous and current version numbers and received a great draft. All I needed to do was to fill in the summary with "Now compatible with Drupal 11!". Put the same into the short description and saved the release.
Voilà, https://www.drupal.org/project/upgrade_rector/releases/2.0.0-alpha3 is available with support for Drupal 9, 10 and 11. It is all proven with my tests. And I never left my browser to achieve this!
There are more complicated cases
Of course there are more complicated cases. I'm planning a followup blog post to expand on this with DrupalPod (based on GitPod) to cover how you can manually test merge requests still without leaving the browser.
If you will be at DrupalCon Portland 2024, we are also organizing mentorship opportunities to learn more about GitLab CI for your project and getting your code ready for Drupal 11. See you there!