Johnattan asked for some help in crafting the message to send to maintainers of modules with drush contrib commands, and I thought this might warrant some review and maybe discussion.

Note that modules that do not modernize will work with both drush 2.1 and drush-HEAD, whereas that those that do will work only with drush-HEAD. Perhaps it might be worthwhile to add some "forward-compatibility" patches to the up-and-coming 2.2 stable branch, to provide some overlap?

Subject: Recent drush changes require modifications to all modules with drush command interfaces

Recently, as part of the evolving drush-3 branch, changes to drush core require modification to all drush commands. There are two relevant changes:

1. Multi-word command names must now be separated with dashes instead of spaces

2. The drush hook function name generating algorithm has been changed to simplify function names where the command name contains the commandfile name; for example, drush_sql_sql_sync becomes drush_sql_sync, and drush_pm_pm_enable becomes drush_pm_enable.

The changes required are easy to make.

1a. In function commandfile_drush_help, change all "drush:my command" to "drush:my-command".

1b. In function commandfile__drush_command, change all $items['my command'] to $items['my-command'].

2b. Rename all drush hook functions that have repeated words due to the command prefix being identical to the command file.

The hook function rename can be done with the following sed script:

$ find -type f -exec sed -i -e 's/\(function drush_\)\([a-zA-Z]\+\)\(_\2\)/\1\2/' {} \;

Unfortunately, making these changes will make the drush commands incompatible with the stable drush 2.1 branch.

For more information, see issues #550522: Change white spaces in commands by another symbol and #678574: Add "pm-" namespace to all of the pm commands, and the comment before the function drush_invoke in includes/command.inc.

Comments

anarcat’s picture

anarcat commented

I think that "deprecation" means that we still support the old stuff, but we have a warning and will completely drop it in a future release.

So this should be part of the 3.x API: pm- and dashes are the new way, the old way is still supported but deprecated for all of the 3.x release branch (see also #682644: Provide a stable release branch). 4.x will drop support for the old way, without a warning at all: just fail.

We should push an alpha release to let people try this out easily.

moshe weitzman’s picture

moshe weitzman commented

I'm not too keen on that much backwards compat. I want to remove all support for spaces in commands for 3.x. This issue is about making that less painful for everyone.

anarcat’s picture

anarcat commented

Well, if 3.x is viewed as a stable release, with no API changes, it makes sense to keep backward compatibility with 2.x. Keep in mind that HEAD would immediately drop support for 2.x spaces-in-commands stuff as soon as a 3.x RC is pushed out.

Otherwise this is not deprecation: it's just removing the thing straight out. To make the transition easier would mean to deprecated it (warn about it) in one release and remove it in the next one. I think that's what stable branches are for...

But I understand if you'd want to get rid of it completely. It's just that I'm giving up on the idea of making a 2.2 release so that would mean there would be no release actually deprecating the spaces stuff.

As much as we want to evangelize and communicate this people, in the end the best effect will be reached through warnings in the actual code. If the code fails silently just after an upgrade, that will be much more difficult for people to adjust.

Those things take time, let them follow. :)

greg.1.anderson’s picture

greg.1.anderson commented

For the record, "deprecated" means "strongly discouraged". This can be interpreted as "supported now but not later" or "unsupported" or a bunch of other things. As mentioned, though, removed completely is not "deprecated", that's "prohibited" or "obsolete".

I think that the main reason to provide backwards compatibility is to allow modules with drush commands to work on both 2.x and 3.x at the same time. If Aegir is not going to use 2.x, then we have no 2.x branch maintainer, and we might as well deprecate 2.x, remove backwards compatibility in 3.x, and encourage everyone to come along. If there's still life in the 2.x branch, though, I'd keep in the backwards compatibility in 3.x for a while to give people an option of which supported drush branch to use without having to fork their own code. There's no point in providing that luxury for an unsupported drush branch, though.

anarcat’s picture

anarcat commented

I don't think I'll fight for a 2.x branch. Too complicated, and Aegir is following HEAD now. So that's out.

However, it would be nice to provide at least a release for people to *try* their changes when they're porting their modules. Basically, people would upgrade to 3.0, and then remove all warnings, and run their modules like this for a while, until they found all the warnings (you *can* miss some, I know we did). If we don't make a release at all that's backward compatible, it will be more difficult to make this work smoothly. We should at least have a test release out there. I would advocate a whole branch that would support the two command sets, not to support the 2.x branch, but to make transitions easier for people coming from that branch to 3.x.

But I'm not so strongly attached to this issue that I will argue to death about it here. :)

greg.1.anderson’s picture

greg.1.anderson commented

I strongly agree with #5; you can do that now with drush-HEAD. It's largely a question of when to obsolete spaces. I also think it should happen later than now, but it can happen prior to "drush-4" if the 2.x branch is deprecated. The distinction is more one of naming than timing, I think, but in any event it does affect what we tell drush command maintainers.

It sounds like the message above is okay, with modifications needed only to the following:

Unfortunately, making these changes will make the drush commands incompatible with the stable drush 2.1 branch.

If the 2.x branch is in fact going to be deprecated, then I think we should decide that now and put words to that effect in the message. "You'd might as well track drush-3, because drush-2 is not maintained any longer."

moshe weitzman’s picture

moshe weitzman commented

OK, thats decided. 2.x will not be maintained any longer and should be considered stable. 3.x and subsequent branches will be treated with more love and care. Unless something changes, it looks like anarcat will be the 3.x branch maintainer.

moshe weitzman’s picture

moshe weitzman commented

I'll bet that most maintainers are using the 'callback' element in their command definitions. We should probably discourage that in this document.

The whole remote command feature is new to 3.x so that might merit a mention. We should mention rsync and sql sync as examples of the beginnings of interesting new apps built upon drush. And Aegir of course.

I'm kinda interested in launching a web site for all things drush. I've been resisting for a while but maybe now is the time. The Drupal handbook is way too big and disorganized to be useful for this purpose ... Arto offerred me drush.com/org/net when I took over maintaining the project but I must have been feeling pretty poor that day because I told him to just let them lapse. Oy - so dumb. I just emailed the current owner of drush.org to see if he will transfer it.

greg.1.anderson’s picture

greg.1.anderson commented

Those are all good ideas. I'm also working on #691174: Allow drush command files to define functions that control whether or not they will be loaded. Patch coming shortly; it might be good to wait for this to land first too.

Too bad about drush.org; seems that a squatter has it. Let me know what the ransom is. Maybe we could use drush.drupal.org?

moshe weitzman’s picture

moshe weitzman commented

Can we revive this? We'll keep the spaces backwards compat for drush3.

greg.1.anderson’s picture

greg.1.anderson commented
Version: » 8.x-6.x-dev
Status: Active » Closed (won't fix)
Issue tags: +Needs migration

This issue was marked closed (won't fix) because Drush has moved to Github.

If desired, you may copy this task to our Github project and then post a link here to the new issue. Please also change the status of this issue to closed (duplicate).

Please ask support questions on Drupal Answers.