Improve update.php language on modules page

Active and specific wording is always good.

"Update to apply the upgrades of modules X, Y, and Z."

Not great yet, but trying to get the "you put the new module files in place but you're not finished yet" in there.

Perhaps the following is better. In addition to more specific language, it also makes the user aware of the consequences of *not* running update.php.

'You must run update.php every time a module is upgraded to complete the upgrade. Failure to do so may result in broken modules.'

What may be best, from a usability perspective, would be to store the installed module version in the system table. When loading the module page, check if the version in the .info file is greater than the version stored in the system table. If this is the case, it indicates that a new version has been uploaded to the site, in which case we would display this using a drupal_set_message() warning.

Hmmm... I'd like some feedback on this idea. If it has a positive reception, I will implement it.

I'd like to hear which approach would bjaspan's friend help best. I think suggestion in #3 removes the part that explicitily "now" is the time you update etc.

I endorse #3.

Proposed in #3:
You must run update.php every time a module is upgraded to complete the upgrade. Failure to do so may result in broken modules

Maybe add a little why do we do it:

It is required to run update.php when a module is upgraded to keep the database up to date and complete the process. Failure to do so may result in broken modules or errors.

EDIT: I removed the first person as is in the handbook guidelines but keep the importance or urgency of the update action.

shouldn't this be task?

Patch attached to modify the wording. New wording is:

Each time a module is updated, you must run update.php to update the database. Failure to do so may result in broken modules or errors. To help manage the update process, the Update status module, if enabled, provides information on new versions of modules (and themes) as they are released. Regular review of the available updates page is essential to maintaining a secure and current site.

The bolding is to help show which portions have changed from the current text. The current text (for comparison's sake) is:

Each time a module is updated, it is important that update.php is run. To help manage the update process, the Update status module, if enabled, provides information on new versions of modules (and themes) as they are released. Regular review of the available updates page is essential to maintaining a secure and current site.

"You must", "Failure to do so"… This is turning into very condescending language. As important as it is to run update.php, Drupal should not have to use this tone of voice to get the point across. Adding more words is not the way to convince people either. People don't read, they scan. Strategy should be to put the most important part first, use simple language and omit needless words.

I propose:

Run update.php each time a module is updated. It updates the database and prevents errors or broken modules. Use the Update status module to recieve information about new versions of modules and themes. Review the available updates regularly to keep your site current and secure.

agree, sounds friendly and has added information.
I am not much on structured grammar..

Just a thought, Maybe condense it:

Run update.php each time a module is updated to update the database, prevent errors and broken modules.

Edit, that's not right, maybe:
Run update.php each time a module is updated to prevent errors, broken modules and update the database.

there just isn't a shorter way of saying it, thinking about the idea of people scanning instead of reading.

unless, maybe taking out the broken part..

Run update.php each time a module is updated to prevent errors and update the database.

Don't why i just keep getting ideas..

Run update.php each time a module is updated to prevent errors, update modules and the database.

it's up to you folks, I appreciate being able to participate. Drupal Rocks!

Still a valid issue. Moving to 8.x, as no new UX changes will be committed to 7.x. See attached screenshot or the text below for the text displayed on admin/modules in 7.0.

Download additional contributed modules to extend Drupal's functionality.

Regularly review and install available updates to maintain a secure and current site. Always run the update script each time a module is updated.

As part of the DrupalCon 2016 Mentored sprint, I am reviewing this ticket.

The language essentially the same after this 5-year old comment;

Download additional contributed modules to extend your site's functionality.

Regularly review and install available updates to maintain a secure and current site. Always run the update script each time a module is updated.

My simple recommendation: change: "Always run the update script each time a module is updated." to "Always run the update script every time you update any module."

There are three places in code where this happens, once in system.module and twice in update.module.

In checking the Content Style Guide and other samples of text, especially in the system_help() the voice change does seem appropriate. I am attaching a patch for reviewing that makes the currently proposed changes so we have something to test and alter.

I am not including an interdiff because the text has changed dramatically from the previous patches due to changes from other issues.

As another point, many important actions are modified with "should" and I was wondering if "must" might be a more appropriate term for this. As an example, "must" is used only once in system_help to describe the need to run cron regularly:

In order for the site and its modules to continue to operate well, a set of routine administrative operations must run on a regular basis; these operations are known as cron tasks.

(emphasis added by me for demonstration).

The issue with changing to "must" is that there are, of course, instances when running update.php is not necessary (i.e., no modules made hook_update_n changes). In that case, running update.php does not cause problems, it will simply tell you that there are no updates to process. This makes me wonder what folks think of:

Regularly review available updates to maintain a secure and current site. After installing module updates, you must run the update script.

While it is not absolutely necessary, it is quite important for the script to run if there actually are updates and I could see that the emphasis could be more important than the technical outliers.

I made my patches against 8.2.x-dev, as the language is still present in this branch.

I do not wish to step on eporama's fine work, but I do wish to submit my patch, if for academic purposes. I've read eporama's commit, and I prefer the language in that commit.

@screenack, thanks for continuing the work! I didn't realize you were looking to complete the patch process, so wanted to make sure your work was testable and committable. Our patches don't differ from what I can see (for anyone else reviewing this), so no disagreement here.

I've checked the patch and ensured that text is changed where appropriate. Screenshots have been added.

This will break translations as existing text is being changed.

Btw, the test failures appear to be a by product of #2724871: Random failure in \Drupal\migrate_drupal_ui\Tests\d7\MigrateUpgrade7Test