This is the third in a series of blog posts about the relationship between Drupal and Backdrop CMS, a recently-released fork of Drupal. The goal of the series is to explain how a module (or theme) developer can take a Drupal project they currently maintain and support it for Backdrop as well, while keeping duplicate work to a minimum.
- In part 1, I introduced the series and showed how for some modules, the exact same code can be used with both Drupal and Backdrop.
- In part 2, I showed what to do when you want to port a Drupal module to a separate Backdrop version and get it up and running on GitHub.
- In part 3 (this post), I'll wrap up the series by explaining how to link the Backdrop module to the Drupal.org version and maintain them simultaneously.
Linking the Backdrop Module to the Drupal.org Version and Maintaining Them Simultaneously
In part 2 I took a small Drupal module that I maintain (User Cancel Password Confirm) and ported it to Backdrop. In the end, I wound up with two codebases for the same module, one on Drupal.org for Drupal 7, and one on GitHub for Backdrop.
However, the two codebases are extremely similar. When I fix a bug or add a feature to the Drupal 7 version, it's very likely that I'll want to make the exact same change (or at least an extremely similar one) to the Backdrop version. Wouldn't it be nice if there were a way to pull in changes automatically without having to do everything twice manually?
If you're a fairly experienced Git user, you might already know that the answer is "yes". But if you're not, the process isn't necessarily straightforward, so I'm going to document it step by step here.
Overall, what we're doing is simply taking advantage of the fact that when we imported the Drupal.org repository into GitHub in part 2, we pulled in the entire history of the repository, including all of the Drupal commits. Because our Backdrop repository knows about these existing commits, it can also figure out what's different and pull in the new ones when we ask it to.
In what follows, I'm assuming a workflow where changes are made to the Drupal.org version of the module and pulled into Backdrop later. However, it should be relatively straightforward to reverse these instructions to do it the other way around (or even possible, but perhaps less straightforward, to have a setup where you can do it in either direction).
- To start off, we need to make our local clone of the Backdrop repository know about the Drupal.org repository. (A local clone is obtained simply by getting the "clone URL" from the GitHub project page and copying it locally, for example with the command shown below.)
git clone firstname.lastname@example.org:backdrop-contrib/user_cancel_password_confirm.gitFirst let's check what remote repositories it knows about already:
$ git remote -v origin email@example.com:backdrop-contrib/user_cancel_password_confirm.git (fetch) origin firstname.lastname@example.org:backdrop-contrib/user_cancel_password_confirm.git (push)No surprise there; it knows about the GitHub version of the repository (the "origin" repository that it was cloned from). Let's add the Drupal.org repository to this list and check again:
$ git remote add drupal http://git.drupal.org/project/user_cancel_password_confirm.git $ git remote -v drupal http://git.drupal.org/project/user_cancel_password_confirm.git (fetch) drupal http://git.drupal.org/project/user_cancel_password_confirm.git (push) origin email@example.com:backdrop-contrib/user_cancel_password_confirm.git (fetch) origin firstname.lastname@example.org:backdrop-contrib/user_cancel_password_confirm.git (push)The URL I used here is the same one I used in part 2 to import the repository to GitHub (that is, it's the public-facing Git URL of my project on Drupal.org, available from the "Version control" tab of the drupal.org project page, after unchecking the "Maintainer" checkbox - if it’s present - so that the public URL is displayed). I've also chosen to give this repository the name "drupal". (Usually the convention is to use "upstream" for something like this, but in GitHub-land "upstream" is often used in a slightly different context involving development forks of one GitHub repository to another. So for clarity, I'm using "drupal" here. You can use anything you want to.)
- Next let's pull in everything from the remote Drupal repository to our local machine:
$ git fetch drupal remote: Counting objects: 4, done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. From http://git.drupal.org/project/user_cancel_password_confirm * [new branch] 7.x-1.x -> drupal/7.x-1.x * [new branch] master -> drupal/master * [new tag] 7.x-1.0-rc1 -> 7.x-1.0-rc1You can see it has all the branches and tags that were discussed in part 2 of this series. However, although I pulled the changes in, they are completely separate from my Backdrop code (the Backdrop code lives in "origin" and the Drupal code lives in "drupal"). If you want to see a record of all changes that were made to port the module to Backdrop at this point, you could run git diff drupal/7.x-1.x..origin/1.x-1.x to examine them.
- Now let's fix a bug on the Drupal.org version of the module. I decided to do a simple documentation fix: Fix documentation of form API functions to match coding standards
I made the code changes on my local checkout of the Drupal version of the module (which I keep in a separate location on my local machine, specifically inside the sites/all/modules directory of a copy of Drupal so I can test any changes there), then committed and pushed them to Drupal.org as normal.
- Back in my Backdrop environment, I can pull those changes in to the "drupal" remote and examine them using git log:
$ git fetch drupal remote: Counting objects: 5, done. remote: Compressing objects: 100% (3/3), done. remote: Total 3 (delta 2), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. From http://git.drupal.org/project/user_cancel_password_confirm 7a70138..997d82d 7.x-1.x -> drupal/7.x-1.x $ git log origin/1.x-1.x..drupal/7.x-1.x commit 997d82dce1a4269a9cee32d3f6b2ec2b90a80b33 Author: David Rothstein Date: Tue Jan 27 13:30:00 2015 -0500 Issue #2415223: Fix documentation of form API functions to match coding standards.Sure enough, this is telling me that there is one commit on the Drupal 7.x-1.x version of the module that is not yet on the Backdrop 1.x-1.x version.
- Now it's time to merge those changes to Backdrop. We could just merge the changes directly and push them to GitHub and be completely done, but I'll follow best practice here and do it on a dedicated branch with a pull request. (In reality, I might be doing this for a more complicated change than a simple documentation fix, or perhaps with a series of Drupal changes all at once rather than a single one. So I might want to formally review the Drupal changes before accepting them into Backdrop.) By convention I'm going to use a branch name ("drupal-2415223") based on the Drupal.org issue number:
$ git checkout 1.x-1.x Switched to branch '1.x-1.x' $ git checkout -b drupal-2415223 Switched to a new branch 'drupal-2415223' $ git push -u origin drupal-2415223 Total 0 (delta 0), reused 0 (delta 0) To email@example.com:backdrop-contrib/user_cancel_password_confirm.git * [new branch] drupal-2415223 -> drupal-2415223 Branch drupal-2415223 set up to track remote branch drupal-2415223 from origin. $ git merge drupal/7.x-1.x Auto-merging user_cancel_password_confirm.module Merge made by the 'recursive' strategy. user_cancel_password_confirm.module | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-)In this case, the merge was simple and worked cleanly. Of course, there might be merge conflicts here or other changes that need to be made. You can do those at this time, and then git push to push the changes up to GitHub.
- Once the changes are pushed, I went ahead and created a pull request via the GitHub user interface, with a link to the Drupal.org issue for future reference (I could have created a corresponding issue in the project's GitHub issue tracker also, but didn't bother):
Here's the commit for Drupal, and the same one for Backdrop:
Using the above technique, it's possible to have one main issue (in this case on Drupal.org) for any change you want to make to the module, do essentially all the work there, and then easily and quickly merge that change into the Backdrop version without the hassle of repeating lots of manual, error-prone steps.
Hopefully this technique will be useful to developers who want to contribute their work to Backdrop while also continuing their contributions to Drupal, and will help the two communities continue to work together. Thanks for reading!
Further Backdrop Resources
- Converting modules to Backdrop from Drupal 7 (official documentation)
- Porting a Module to Backdrop - Basics (YouTube video by Backdrop co-founder Nate Haug a.k.a. quicksketch)
- Backdrop change records (official list of important changes from Drupal 7)
- Instructions for applying to the Backdrop contributed project group on GitHub
- Backdrop core repository on GitHub
- Main Backdrop CMS site (including links to download the code or spin up an automatic Backdrop demo site)
- Backdrop CMS: Setting The Record Straight (recent Drupal Watchdog article by Backdrop co-founders Jen Lampton and Nate Haug)
Do you have any thoughts or questions, or experiences of your own trying to port a module to Backdrop? Leave them in the comments.
Deploy Anywhere, Monitor Everything Drupal.
Take the headache out of Drupal security with Tag1 Quo - Drupal Monitoring Made Easy.