MAINTENANCE

This section describes how to maintain Drush Make lockfiles. To understand how to build platforms using them, please see the Usage section. To better understand how these makefiles are structured, please see the Structure section.

Please follow the installation instructions in the Install section, as we currently recommend using a git version of Drush. The usage instructions below assume that you have followed those instructions exactly.

For simplicity, we use the "demtools/dkan" project (unless otherwis specified) in our examples. Obviously, replace this with whichever platform is appropriate.

Drush Make lockfiles

The principle benefit of using lockfiles, over regular makefiles, is that they allow us to build the same platform in a repeatable fashion. A lockfile is simply a type of makefile generated by Drush, that specifies all the versions for all the included projects. Otherwise, we might get a different platform each time we build, depending on how many projects we include, their release cycle and/or the pace of their development.

Also, lockfiles allow us to build platforms using the lockfiles remotely, without having to be concerned with any includes being specified locally. For example, we can use the raw output of a git repository containing such a lockfile, and be confident that any subseqent platform built with that same URL will be identical.

Update your makefiles

Under normal circumstances, you'll only need to modify makefiles to add or remove components from your platform build. Some (very few) makefiles require manual updates to version numbers. The only use-case we are currently aware of is when downloading a project or library using the get download type. An example of this can be seen in makefiles/stock/civicrm/contrib.make.yml:

projects:
  civicrm:
    type: module
    download:
      type: get
      url: 'http://downloads.sourceforge.net/project/civicrm/civicrm-stable/4.6.13/civicrm-4.6.13-drupal.tar.gz'

We can see the result of updating a makefile by building our lockfiles with make all and git diff. But that is covered in more detail in the next section.

Pinning major versions

Occasionally we'll see a new major version of a project released. By default, Drush Make will select the most recent supported version of a project. As a result, our lockfiles would show a major version bump as well. Generally speaking, major version upgrades of modules are not a part of the day-to-day maintenance of platforms. They will likely require some manual intervention, or, at very least, thorough testing.

Assuming the current version of such a component is still supported, the most expedient solution is likely to involve pinning a major version for the module. This allows new releases on that branch to be incorporated automatically.

For example, in makefiles/demtools/civicrm/contrib.make.yml, we could replace this:

projects:
  webform:  { version: ~ }

With the following:

projects:
  webform:
    # The recommended release is on the 4.x branch, so we pin to the latest
    # supported version on the 3.x branch.
    version: 3

Note that it is usually worthwhile to document the reasons for such pinning. Rebuild the lockfiles, and check what has changed:

$ make all
tmp/drush make-lock makefiles/demtools/civicrm/build.yml --result-file=makefiles/demtools/civicrm/lock.yml
Wrote .make file makefiles/demtools/civicrm/lock.yml                                                                       [ok]
$ git diff makefiles/demtools/civicrm/lock.yml

The resulting diff should show something like this:

diff --git a/makefiles/demtools/civicrm/lock.yml b/makefiles/demtools/civicrm/lock.yml
index d3ab256..212a373 100644
--- a/makefiles/demtools/civicrm/lock.yml
+++ b/makefiles/demtools/civicrm/lock.yml
@@ -58,7 +58,7 @@ projects:
   webform_civicrm:
     version: '4.15'
   webform:
-    version: '4.12'
+    version: '3.24'
   libraries:
     version: '2.2'
   options_element:

Update the lockfiles

We use a GNU Makefile to simplify updates to lockfiles. This Makefile defines dependencies between the various lockfiles, and their includes. This means that when a (Drush) makefile is updated, all lockfiles that include that makefile will be rebuilt.

Since we keep all our lockfiles in git, it's often easiest to simply force the re-compilation of all the lockfiles:

$ make all -B
tmp/drush make-lock makefiles/cores/drupal7/build.yml --result-file=makefiles/cores/drupal7/lock.yml
Wrote .make file makefiles/cores/drupal7/lock.yml                                                                          [ok]
tmp/drush make-lock makefiles/cores/drupal8/build.yml --result-file=makefiles/cores/drupal8/lock.yml
Wrote .make file makefiles/cores/drupal8/lock.yml                                                                          [ok]
tmp/drush make-lock makefiles/stock/dkan/build.yml --result-file=makefiles/stock/dkan/lock.yml
Wrote .make file makefiles/stock/dkan/lock.yml                                                                             [ok]
tmp/drush make-lock makefiles/stock/civicrm/build.yml --result-file=makefiles/stock/civicrm/lock.yml
Wrote .make file makefiles/stock/civicrm/lock.yml                                                                          [ok]
tmp/drush make-lock makefiles/demtools/dkan/build.yml --result-file=makefiles/demtools/dkan/lock.yml
Wrote .make file makefiles/demtools/dkan/lock.yml                                                                          [ok]
tmp/drush make-lock makefiles/demtools/civicrm/build.yml --result-file=makefiles/demtools/civicrm/lock.yml
Wrote .make file makefiles/demtools/civicrm/lock.yml                                                                       [ok]

A quick git diff will then show any updates to lockfiles.

This behaviour is based on file timestamps, even if the contents have not changed. To see it in action, you can test it with:

$ touch makefiles/stock/dkan/contrib.make.yml
$ make all
tmp/drush make-lock makefiles/stock/dkan/build.yml --result-file=makefiles/stock/dkan/lock.yml
Wrote .make file makefiles/stock/dkan/lock.yml                                                                             [ok]
tmp/drush make-lock makefiles/demtools/dkan/build.yml --result-file=makefiles/demtools/dkan/lock.yml
Wrote .make file makefiles/demtools/dkan/lock.yml                                                                          [ok]

As you can see, updating the timestamp on a single file, triggered updates to the two lockfiles that include it. In fact, only makefiles/stock/dkan/lock.yml depends directly on makefiles/stock/dkan/contrib.make.yml. The demtools/dkan lockfile depends on the stock dkan lockfile, and so is rebuilt when that one is updated.

Test the new lockfile

It is usually worthwhile to test the new lockfile at this point. For example, an update to a module could cause a patch to no longer apply. Usually, in such cases, updating the makefile with a new patch, or simply removing patches that have been incorporated into the new release, will be sufficient to resolve any issues at this stage.

Adding or changing patches or libraries, adding new modules or themes, and other such modifications can also cause build failures. Running a test build is as simple as running:

$ make demtools/dkan-test
Beginning to build makefiles/demtools/dkan/lock.yml.           [ok]
drupal-7.43 downloaded.                                        [ok]
[...]

Each DemTools platform (demtools/dkan, demtools/civicrm, etc.) have such a test command defined (although it may not show up in the make list output).

Note that running such a test will re-compile any relevant lockfiles whose sources have changed.

Finalize the new lockfile

Once any changes or updates are done, we can then commit these changes into git:

$ git commit -am"Update DemTools platforms."