Improve the plugin/theme auto-update emails

[desrosj]

Follow up of #50052.

The current email notifying the site admin of automatic plugin and/or theme updates feels incomplete and could use some more context.

My two main concerns are:

• It's not clear if any action is required by the site owner.
• It's not clear where the site lives (no link is included in the email body).

The current email when plugins and themes successfully auto-update is as follows:

The following plugins were successfully updated:

• Hello Dolly

The following themes were successfully updated:

• Twenty Twenty

If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
​https://wordpress.org/support/forums/

The WordPress Team

I am suggesting it gets updated to something like the following:

Howdy! Some plugins and/or themes have been updated automatically to new versions on your site at ​https://site.com. No further action is needed on your part!

The following plugins were successfully updated:

• Hello Dolly

To manage plugins on your site, visit the Plugins page: ​https://site.com/wp-admin/plugins.php

The following themes were successfully updated:

• Twenty Twenty

To manage themes on your site, visit the Themes page: ​https://site.com/wp-admin/themes.php

If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
​https://wordpress.org/support/forums/

The WordPress Team

[audrasjb]

Upgrade/Install: Improve plugins and themes auto-updates email notifications

[audrasjb]

Thanks for opening this ticket.
I made a first patch to test your initial proposal.
It looks nice to me. Waiting for further copy review.

[desrosj]

Thanks for the patch, @audrasjb! I dug a bit deeper and also examined the mixed and failure emails. Those already have opening sentences, so I think this will be great for bringing the success emails more in line.

One additional thing to flag is that the success and mixed results emails currently have the same subject line. This is a bit concerning because someone would have no way of knowing there was a failure unless they actually opened and read the email. The subject line should make it clear that there was a problem auto-updating something on the site, even if there were also successful updates.

50268.2.diff​ works off of 50268.diff​ to further refine:

• Subject lines are now separated out for each combination to avoid the need for "and/or". For example, if only plugins were updated, themes will no longer be mentioned and the subject will be "Some plugins were automatically updated".
• Some logic was shifted to avoid duplicate code.
• Moved the admin links for plugins and themes below the list of plugins/themes updated so the list of affected items flows a bit better.

I also tweaked the success introduction added in 50268.diff​ based on my suggestion above to read have been updated automatically from have been automatically updated to be more consistent with the subject lines, and align more with "auto-update".

I'm not crazy about creating 3 new variables at the top of the function, but repeating those conditions also felt wrong.

An email with successful plugin and theme updates will now read (with the subject line "[Site Name] Some plugins and themes were automatically updated"):

Howdy! Some plugins and themes have been updated automatically to new versions on your site at http://site.test. No further action is needed on your part.


The following plugins were successfully updated:
- Classic Editor


The following themes were successfully updated:
- Twenty Twenty


To manage plugins on your site, visit the Plugins page: http://site.test/wp-admin/plugins.php
To manage themes on your site, visit the Themes page: http://site.test/wp-admin/themes.php


If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
https://wordpress.org/support/forums/

The WordPress Team

An email with failed results will now read (with the subject line "[Site Name] Some plugins and themes have failed to update"):

Howdy! Failures occurred when attempting to update plugins and themes on your site at http://site.test.

Please check out your site now. It’s possible that everything is working. If it says you need to update, you should do so.


The following plugins failed to update:
- Classic Editor


The following themes failed to update:
- Twenty Twenty


To manage plugins on your site, visit the Plugins page: http://site.test/wp-admin/plugins.php
To manage themes on your site, visit the Themes page: http://site.test/wp-admin/themes.php


If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
https://wordpress.org/support/forums/

The WordPress Team

An email with mixed results will now read (with the subject line "[Site Name] Some plugins and themes have failed to update"):

Howdy! Failures occurred when attempting to update plugins and themes on your site at http://site.test.

Please check out your site now. It’s possible that everything is working. If it says you need to update, you should do so.


The following plugins failed to update:
- Classic Editor


The following themes were successfully updated:
- Twenty Twenty


To manage plugins on your site, visit the Plugins page: http://site.test/wp-admin/plugins.php
To manage themes on your site, visit the Themes page: http://site.test/wp-admin/themes.php


If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
https://wordpress.org/support/forums/

The WordPress Team

[audrasjb]

Thanks @desrosj for your refinements, 50268.2.diff looks really great to me.
I didn't saw anything wrong on my tests.

[azaozz]

The emails look good here too. This code can be simplified at the cost of making the text a little more generic, but on the other hand the emails sound pretty good now, imho.

[Presskopp]

I'd expect version numbers like in

The following plugins were successfully updated:
- Some Plugin (1.2 -> 1.3)

[garrett-eclipse]

I'll second @Presskopp that version information is helpful.

As well if counts are available they can be used to indicate number of fail/success items and the strings can then be pluralized;
"The following plugin failed to update:" / "The following 2 plugins failed to update:"

Also would it make sense to group the plugin items and theme items separately so after the list of plugins you have the link to plugins admin screen, whereas currently the links are slightly disassociated from their lists.

[desrosj]

@Presskopp @garrett-eclipse I'm not sure I like including version numbers in this email for a few reasons.

Plugin and theme version numbers are not standardized in any way. One plugin could have version x.xx.x.x and another could have x.x. This could be very confusing and overwhelming to anyone that is not technical (information overload). The Core versions are included because they are standardized, they are always accompanied by documentation, and there are release posts/field guides that accompany each release.

It also places stress on the version. Which, for the majority of site owners won't matter. As we move towards the lofty goal of more frequent, seamless releases (ideally similar to the browser versioning where it just updates and works), the importance of the version number should fade away.

I do see how it may be important to some. If there is a lot of support for adding the version numbers, I'd see about disabling that by default and maybe having a filter to include those versions. I'm interested in what others think, though.

Another thing I wanted to mention for any of our copy review folks that may hop in and help out. The goal here is to match the tone of the current Core auto-update emails as best as possible. There are no plans to modify those Core auto-update emails at this time. So matching the tone and feel in the plugin/theme emails is important for consistency and making this new feature feel natural.

[paaljoachim]

In general the wording can be improved. It should also be shorter.
Some adjustments.

Please remove the word: "Howdy!"
It has always sounded like slang and as I have also read comments over time from various people who feels that it is unprofessional.

For instance it's to it is.
Please check out your site now. = Please check your site now.

Remove:
To manage plugins on your site, visit the Plugins page: ​http://site.test/wp-admin/plugins.php
To manage themes on your site, visit the Themes page: ​http://site.test/wp-admin/themes.php
(This information is really not needed in the e-mail.)

Adjusting:
Please check your site now. It is possible that everything is working. If it says you need to update, you should do so.
=
Check your site for any errors and follow any messages. Update the site if needed.

Adjusting:
If you experience any issues or need support, the volunteers in the WordPress.org support forums may be able to help.
​https://wordpress.org/support/forums/

(Too many words.)

Adjust to:

For support go to/visit ​https://wordpress.org/support/forums/

---

New suggestion.
The check your site sentence still needs work.

Failures occurred when attempting to update plugins and themes on your site at http://site.test.

Check your site for any errors and follow any messages. Update the site if needed.

The following plugins failed to update:
- Classic Editor

The following themes were successfully updated:
- Twenty Twenty

For support go to https://wordpress.org/support/forums/ 

The WordPress Team

[garrett-eclipse]

Thanks @desrosj I think version is mostly helpful to search and support. If there's a recurring failure and a search on google is done with version number it's more likely to surface. As well when posting to support they'll just copy the email and if version info is available it means support has that to work from. But yes maybe that's more a enable-able thing as could be seen as overwhelming to some.

[johnbillion]

I'm inclined to say that including version numbers in the email adds more noise than necessary, but I agree that it could be useful for fault finding.

If version numbers aren't included in the email, what other means are available to the user to identify which version the plugin just updated from and to?

There should be a link to the admin area somewhere in the email, although I agree the separate links to the plugins and themes screens are unnecessary. Paal's suggestions are all good.

[johnbillion]

This may be a separate issue, but under what conditions might a plugin automatic update fail and therefore trigger the failure email message? If it does fail and the problem is persistent, when does it next attempt to update? If I don't check my emails for let's say three days, how many failure emails might I have in my inbox?

I ask in case we need to consider some failure tolerance here to avoid too many failure emails being sent out.

[marybaum]

My first thought is about the phrase 'successfully updated', which I'd actually like to change project-wide, but we can get a good start here -- it's redundant.

So let's change

Howdy! Some plugins and themes have been updated automatically to new versions on your site at ​http://site.test. No further action is needed on your part.

The following plugins were successfully updated:

• Classic Editor

The following themes were successfully updated:

• Twenty Twenty

to

Howdy! Some plugins and themes have updated automatically to the latest version.

The following plugins are now up to date:

-Classic Editor

The following themes are now up to date:

-Twenty Twenty

[marybaum]

Now to edit the rest of the copy -- I'll include the new success messages in place.

On the success email:

"Howdy! Some plugins and themes have updated automatically to the latest version.

The following plugins are now up to date:

-Classic Editor

The following themes are now up to date:

-Twenty Twenty

If this is what you expected, you don't need to do anything.

You can make changes to your site's plugins on ​https://site.com/wp-admin/plugins.php and to your themes on ​https://site.com/wp-admin/themes.php.

If you notice unexpected behavior or need support, the volunteers in the WordPress.org support forums may be able to help.

The WordPress Team"

On the mixed email:

"Howdy! Some of the themes and plugins on ​http://site.test updated automatically, but some did not.

Please check out your site now. It’s possible that everything is working, and you won't need to do anything else. If any of your themes or plugins say you should update, please do.

These themes are now up to date:

• Twenty Twenty

These plugins returned errors:

• Classic Editor

You can manage plugins on your site on the Plugins page: ​http://site.test/wp-admin/plugins.php
You can manage themes on your site, visit the Themes page: ​http://site.test/wp-admin/themes.php

If you notice unexpected behavior or need support, the volunteers in the WordPress.org support forums may be able to help.
​https://wordpress.org/support/forums/

The WordPress Team"

On the failure email:

"Howdy! Plugins and themes at ​http://site.test failed to update automatically.

Please check out your site now. It’s possible that everything is working. If you see alerts asking you to update, please do.

These plugins failed to update:

• Classic Editor

Thes themes feailed to update:

• Twenty Twenty

You can manage plugins on your site on the Plugins page: ​http://site.test/wp-admin/plugins.php
You can manage themes on your site, visit the Themes page: ​http://site.test/wp-admin/themes.php

If you notice unexpected behavior or need support, the volunteers in the WordPress.org support forums may be able to help.
​https://wordpress.org/support/forums/

The WordPress Team"

[garrett-eclipse]

Related: #50350

[pbiron]

@garrett-eclipse thanx for adding the related ticket about version numbers.

All further discussion about including version numbers in the emails should happen on that ticket.

[desrosj]

50268.3.diff​ is the next iteration of the emails taking into account feedback above.

In a recent ​office hours chat, a compromise was reached to include the links to Plugin and Theme pages in the admin only if there were failures for those types of updates.

I kept the wording to be automatically updated instead of updated automatically because that matches more closely with auto-updates, and I left the last sentence the same so that it is consistent across all core update emails.

@johnbillion for failure scenarios, I believe that right now the scenarios that would cause a failure (in no particular order) are:

1. No plugin is found in the update package.
2. The plugin is already at the latest version.
3. Upgrader cannot connect to the file system.
4. An error occurs downloading the update package.
5. Signature verification fails (eventually, not currently enforced).
6. Package could not be unzipped.
7. Old version of plugin could not be deleted.
8. New version cannot be copied into the plugin's folder.

wp_version_check happens every 12 hours. So theoretically, some of these could trigger an email every 12 hours.

Let's refine the email here and then tackle tolerance in a new ticket.

[desrosj]

I'm going to get 50268.3.diff​ in as it is an improvement to what's currently included and we can continue to iterate.

[desrosj]

Created #50448 to explore adding a throttle to failure emails. This was also fixed in [48123], but for some reason, it was not posted here.