What is the protocol for adding a new module dependency to a module that has only had a dev release?

Question

I created a module a while ago and it has only had a 7.x-1.x-dev release on Drupal.org for the last month or so. There are a number of reported downloads and installs already for this module so I want to make sure that the handful of users that already are using this module are still considered in the next dev release I need to make. The new release will have a new module dependency that is from another project (i.e. not included as a submodule of mine). While I would normally create a 2.x version if the module had a stable release, it has only been in dev. Do I just go ahead and add the new dependency in the 1.x-dev or create a 2.x-dev?

Answer 1

There's no sanctioned protocol for such a case. All I think of is to minimize the impact.

Consider that even if you create a new branch, users may update and neither realize there's a new dependency, and your module may end up silently disabled because of unmet dependencies. This happened to the update of views from 6.x-2.x to 6.x-3.x where a dependency on ctools was added. In that case, the impact was low because ctools usually is present.

On documentation, in addition to changelog or upgrade doc in the project page, I suggest to add it to the release notes. Since they can be read easily when updating with drush.

Last, if the dependency you're introducing is a popular module, you can alleviate the impact by enabling the new dependency in hook_update_N or raising an error if not available. Here's some untested code:

<?php
function MODULENAME_update_7001() {
  $enabled = module_enable(array('foo', 'bar'));
  if (!$enabled) {
    throw new DrupalUpdateException('foo required.');
  }
}

Answer 2

Apart from what @jonhattan has mentioned, I would suggest one more method to do it. Add those dependency in the mymodule.info file. Lets assume you want to add new dependency to link, email and addressfield.

dependencies[] = link
dependencies[] = email
dependencies[] = addressfield

Now in hook_requirments try to enable the modules automatically if present. Please note that since we have added dependencies in info file, those would be enabled if its a first time install. But otherwise they would appear "locked". In this case we would have to enable them automatically. Now as @jonhattan have answered you could try to do it in hook_update_N and throw an exception when it fails.

But the problem with the above method is the user experience. You cannot output "links" in the exception message. Another is it could be easily be avoided by letting the user know right before an update is attempted. For such case we have hook_requirements.

I will provide an example how to use hook_requirements for the example case i have mentioned.

/**
 * Implements hook_requirements.
 */
function mymodule_requirements($phase) {
  $requirements = array();
  if ($phase == 'update') {
    $enabled = module_enable(array('link', 'email', 'addressfield'));
    if( !$enabled ) {
      $t = get_t();
      $requirements['mymodule_migrate'] = array(
        'title' => $t('Mymodule Migrate Issues'),
        'value' => $t('One or more of the required modules cannot be enabled.
          If you download the modules from Drupal.org those would be enabled automatically when update script is run.
          So Please make sure following modules are present: !link, !email & !addressfield',
          array(
            '!link' => l('link', 'https://drupal.org/project/link'),
            '!email' => l('email', 'https://drupal.org/project/email'),
            '!addressfield' => l('addressfield', 'https://drupal.org/project/addressfield'),
          )
        ),
        'severity' => REQUIREMENT_ERROR,
      );
    }
  }
  return $requirements;
}

Now it is also possible to try to enable each module individually and craft the message properly so that only those modules that are absent are shown in the message.