6

I have a module on drupal.org that is currently just has a -dev branch. The module feature detects for another module, and uses it if available. Otherwise, it can safely ignore it. In other words, it is not listed a dependency in the .info file.

A bug report came in, and it looks like I may need to make this a proper dependency.

Is there proper way to handle this situation which minimizes people breaking sites if they update?

  • For those who know what issue I am talking about, I actually mostly have a workaround for the situation. This question is little more generic, as to better serve future readers. – mpdonadio Oct 17 '13 at 16:21
  • @Bala Not sure how this addresses the problem. – mpdonadio Oct 22 '13 at 9:50
  • Have you considered adding the dependency but also detecting if the module is not present and handling it as gracefully as possible? With a message to the admin so they know things may not quite work, but avoiding there being PHP errors. – Alfred Armstrong Oct 23 '13 at 16:26
9
+250

I would use hook_requirements() for this, at least in your next version.

It takes severity parameter:

The requirement's result/severity level, one of:

  • REQUIREMENT_INFO: For info only.
  • REQUIREMENT_OK: The requirement is satisfied.
  • REQUIREMENT_WARNING: The requirement failed with a warning.
  • REQUIREMENT_ERROR: The requirement failed with an error.

What you want seems to be REQUIREMENT_WARNING

Requirement severity -- Warning condition; proceed but flag warning.

That way admin will see that requirement is not satisfied, but will be able to proceed anyway. I currently have this in one of my projects:

enter image description here

If I click "try again", I can proceed, but I will not be surprised if next version will not allow me to proceed, and I am aware that some important functionality will not work if I will proceed now, without addressing this warning.

It's also a good idea to provide a link to installation instructions or drush installation helper syntax in your warning message, as seen on the screenshot.

It should be a temporary solution only, of course. After a week or two you could move your dependency to .info file. Module users will expect it, informed by your warning, and no further logic or warnings will be needed anymore.

Of course changelog and project's page should be a main source of information about serious changes, but many people update using Drupal's built-in functionality and will not even see module's page before update, so it is unsafe to assume they will know basing only on the assumption you posted it there.

  • 2
    I was once scolded by chx for doing this - hook_requirements() should only ever be used for declaring dependencies on PHP/system libraries. It should never, ever be used for declaring dependencies on modules, apparently. – Clive Oct 22 '13 at 11:51
  • @Clive there is no functionality like this in any other hook or configuration (correct me if I'm wrong). And there is no info about not requiring modules in this hook's documentation. I agree that with hard and simple requirements, info file is the way to go. But it's simply insufficient for complicated situations, so telling people "don't use what works, use something that can't work!" is hardly helpful, no matter who says it. – Mołot Oct 22 '13 at 12:01
  • @Clive by the way, it was OP who told me to use this hook for module requirements few months ago ;) – Mołot Oct 22 '13 at 12:08
  • 1
    Yeah that was my argument too - but I was told in no uncertain terms that I was wrong. That coming from one of the main core devs is enough for me :) – Clive Oct 22 '13 at 12:17
  • @Clive Did he care to provide alternative method that works in cases like this, and my old one? I still need jQuery Update or jQuery Multi in my modules, for example, and I do not care which... And if you can find a link to transcription, I will file a bugreport on hook's documentation ;) – Mołot Oct 22 '13 at 12:20
4

Really this is a greater problem, which is "What do I do if I have made a change that could break people's site", because it isn't limited to dependencies, it can be API changes, removing sub modules, functionality changes, markup changes, etc.

In my opinion I think a note that stands out on the project page and also in the release notes is all you really need.

You can add the note to the project page as soon as the code goes into dev and say that the next release (and the current dev) will have such and such requirement.

You can also add change notices: like https://drupal.org/list-changes/zen

These can be quite descriptive and you can link to them from the project page or release notes, although a lot of people probably don't see the normal link to them off in the sidebar.

You could also add a message that is displayed on screen when upgrading to notify the user if the required module isn't enabled. - This is most useful if the site is not going to completely implode from running one without the other for a single second, for examlpe if the requirement only affects certain areas of the site. Unless of course the requirement is such that the site might break the second you are running one module without the other.

You could then create a new release now with the warning message saying the next version will have a new requirement, and then in a month or however long you deem appropriate, you release a new version with the dependency.

I think that is sufficient. I think people should be able to read the release notes and be responsible for their site.

Plus it will teach them a valuable lesson if they upgrade the module straight on the live site without testing and without reading the release notes & project page.

One final thing, if the change is great enough you might also consider creating a new major version, for example keep the 1.x version as is and create a new 2.x branch for the potentially site breaking change.

In your specific case where you only currently have a dev version you have no obligation to anyone because it is not a proper release and is expected that it could possibly change.

This is the downside of choosing to use a dev or alpha module on your site.

It does make it a bit harder though becasue you can't say as of version 1.1 you now need some module, you can only say as of the dev version on date such and such, there is now this new requirement.

This is where it might be handy to roll a release now and then another later with the dependency.

Note This is obviously also in addition to adding the dependency to the info file and the README file.

Some examples

https://drupal.org/node/959790
https://drupal.org/node/883044 - In this case the module also showed a message to the user in previous versions leading up to the full change.
https://drupal.org/node/1543432
https://drupal.org/node/2022741

  • Can you give any example of modules where this has been done? I have lots of documentation on the project page, and in the status report, and in the README that users ignore already... – mpdonadio Oct 22 '13 at 19:33
  • I'll check when I get a chance. I know people ignore these things but I feel that is their problem, not the module maintainer. People have to take responsibility and shouldn't have to be treated like babies. – rooby Oct 22 '13 at 22:36
  • I especially think it doesn't matter because you don't already have a stable release without the dependency. – rooby Oct 22 '13 at 22:37
  • I have updated the answer – rooby Oct 23 '13 at 10:09
2

I wish you had provided more information here but maybe that was intentional.

The answer is within the question...

The module feature detects for another module, and uses it if available. Otherwise, it can safely ignore it.

Then it's not a dependency, is it?

Maybe an issue was posted that would not have been posted if the user had taken the time to RTFM. Or maybe had a look at the README file, or maybe the online help. But a module on a dev system can behave behaving differently when enabled on a production system and leave even good people scratching their heads.

You are correct in that best efforts in documentation are often ignored. If something works wonderfully out of the box, very few will read the documentation.

When was the last time you read the instructions for xmas lights?

I have a similar dev story. My module has a page with a configurable url. Before this can be changed, url availability must be checked. Drupal offers a variety of functions for this but the are not consistent across D6, 7 & 8 and some not available at all in D8. All fail under some scenarios.

So I opted to write a small purpose built function that made use of the php cURL library. I thought cURL was a pretty common library (it is) and I did not give this much thought. The purpose built function works in all versions of Drupal without modification.

It did not, however, install with Drush because the drush config did not include cURL. Drush did not, at the time, behave very elegantly either, attempting to repeat the same failed process repeatedly without proper error reporting until it gave up or timed out.

I was developing in Windows at the time and did not use drush. This problem confounded me for a long time because it worked for me and others but did not work for some. Those included people who were performing code reviews needed before my sandbox project could become an official Drupal project.

There were also great objections during the review process to the purpose built function -- why not the Drupal standard API functions available? I finally figured out it was a curl dependency when one reviewer finally mentioned it.

My solution was to to use a series of tests for url availability which started with the Drupal API functions. If all of the Drupal API calls passed, then I used a php function_exists('curl_init') call to detect if the library is installed.

So this now works with a drush install with or without cURL being installed. If cURL is installed, it works better, catching that use case that the Drupal API misses altogether.

This is not a dependency, it's a serendipity. (forgive the grammar)

Will I make it a dependency (how is that done?) or implement hook_requirement()? NO WAY. It is not necessary.

Of course this does not deal with the issue of unexpected different behaviour that a serendipity might toss in the face of an admin who was previously delighted with those new xmas lights.

After reading your question and giving it some thought, I reckon I will take this approach:

In the soon-to-be-released 1.0 versions, there will be a message that appears on the admin config screen, in bold colors, announcing that This module will work better with the cURL library installed.

And this message will only appear if the cURL library is NOT installed. I figure that this will be the edge case. Who cares otherwise?

Enjoy your xmas lights.

1

It also sounds like if you're going from -dev to a solid release using this new dependency; maybe you should have a Major version increase to note the new hard dependency. Just food for thought -- Major versions can "break" stuff or require new things, Minor versions should not.

And in my opinion the same for -dev to stable.

  • Between dev and stable there should be at least one alpha, beta, or RC, and transition from it to stable should not break things. Just my two cents. – Mołot Oct 24 '13 at 14:17

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.