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).

  1. 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 git@github.com:backdrop-contrib/user_cancel_password_confirm.git
    First let's check what remote repositories it knows about already: 
    $ git remote -v
origin    git@github.com:backdrop-contrib/user_cancel_password_confirm.git (fetch)
origin    git@github.com: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    git@github.com:backdrop-contrib/user_cancel_password_confirm.git (fetch)
origin    git@github.com: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.)
  2. 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-rc1
    You 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.
  3. 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.

  4. 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.
  5. 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 git@github.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.
  6. 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):
    • Fix documentation of form API functions to match coding standards (pull request) (diff)
    Merging this pull request via the GitHub user interface gets it onto the official 1.x-1.x Backdrop branch, and into the Backdrop version of the module.

Here's the commit for Drupal, and the same one for Backdrop:

http://cgit.drupalcode.org/user_cancel_password_confirm/commit/?id=997d82dce1a4269a9cee32d3f6b2ec2b90a80b33

https://github.com/backdrop-contrib/user_cancel_password_confirm/commit/997d82dce1a4269a9cee32d3f6b2ec2b90a80b33

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

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.
Install in 5 Minutes!