WordPress.org

Make WordPress Core

Opened 5 months ago

Last modified 20 hours ago

#53049 assigned enhancement

Add changelog release notes to auto update email notifications

Reported by: JosVelasco Owned by: josvelasco
Milestone: 5.9 Priority: normal
Severity: minor Version:
Component: Upgrade/Install Keywords: has-patch
Focuses: administration Cc:

Description

The Email currently shows the following when the plugin updates:

[Site name] Some plugins were automatically updated

These plugins are now up to date:
Plugin name (from version x.xx to x.xx)

It could be helpful to include the changelog description of the latest version or add a link to the plugins development tab e.g. https://wordpress.org/plugins/plugin/#developers

Change History (41)

This ticket was mentioned in Slack in #core-auto-updates by francina. View the logs.


5 months ago

#2 @pbiron
5 months ago

  • Component changed from Mail to Upgrade/Install

#3 @pbiron
5 months ago

@JosVelasco thanx for the ticket! And welcome to Trac.

I like the idea of a link to the changelog, but thing including the changelog text in the body of the email messages would be overkill (and make them harder to site admins to see what was updated).

We briefly discussed this ticket on Slack today and there seems to be agreement that this is something that we can work on.

#4 follow-up: @oliverstapelfeldt
4 weeks ago

Hello,

today one of the plugins on one of my sites got updated and I thought that this could be a good point to try (I'm no software developer) my first contribution to WordPress 😃

What is the status of the ticket?

Olli

This ticket was mentioned in Slack in #core-auto-updates by francina. View the logs.


4 weeks ago

#6 in reply to: ↑ 4 @francina
4 weeks ago

Welcome to Trac Olli!
as mentioned in the previous comment, the maintainers of the upgrade/install component think it is a good idea, so it needs a patch :)
What are your thoughts?

Replying to oliverstapelfeldt:

Hello,

today one of the plugins on one of my sites got updated and I thought that this could be a good point to try (I'm no software developer) my first contribution to WordPress 😃

What is the status of the ticket?

Olli

Last edited 4 weeks ago by francina (previous) (diff)

#7 @francina
4 weeks ago

  • Milestone changed from Awaiting Review to Future Release
  • Owner set to josvelasco
  • Status changed from new to assigned

#8 @francina
4 weeks ago

  • Keywords needs-patch added; needs-design removed

#9 follow-up: @oliverstapelfeldt
4 weeks ago

When I first think of the plugin-mail for me it would be enough if the design was

name (from to, changelog)

The link has to be translated.

What do you think?

#10 in reply to: ↑ 9 @JosVelasco
4 weeks ago

Good point about the link pointing to the admin's language.

Replying to oliverstapelfeldt:

When I first think of the plugin-mail for me it would be enough if the design was

name (from to, changelog)

The link has to be translated.

What do you think?

#11 follow-up: @oliverstapelfeldt
4 weeks ago

And for the destination of the link for a plugin in the repository I imagine the tab development with a jump to the heading changelog.

What do you think?

This ticket was mentioned in Slack in #core by francina. View the logs.


4 weeks ago

#13 in reply to: ↑ 11 @JosVelasco
4 weeks ago

That would be awesome but for a first step I'll try to link to https://wordpress.org/plugins/plugin-slug/#developers

Replying to oliverstapelfeldt:

And for the destination of the link for a plugin in the repository I imagine the tab development with a jump to the heading changelog.

What do you think?

#14 @oliverstapelfeldt
4 weeks ago

Do you try?

Meanwhile I think of further questions to be discussed.

#15 @JosVelasco
4 weeks ago

In my testing site, I inserted the following code at the line 1170 in wp-admin/includes/class-wp-automatic-updater.php

$body[] = ( 'https://wordpress.org/plugins/' ) . $item->item->slug . ( '/#developers' );

This adds the link to the plugin's developers tab.

I saw that links are not enclosed to an HTML <a> tag in the e-mail. I don't know if this is on purpose. So for now it takes a whole row, look at the screenshots at the end.

Also I don't know how we could translate the link to the different admin languages.

For me this works well but I don't know if it is enough. It is kind of compact and I like the fact that you can read the plugin's slug.

Desktop example:
https://www.josvelasco.com/53049/wp-content/uploads/2021/08/update-desktop.png

Mobile example:
https://www.josvelasco.com/53049/wp-content/uploads/2021/08/update-mobile.png

#16 follow-up: @oliverstapelfeldt
4 weeks ago

What's the best way to trigger an update for testing?

#17 in reply to: ↑ 16 @JosVelasco
4 weeks ago

  1. I added this function to my theme's functions.php to force auto updates.
    add_filter( ‘automatic_updates_is_vcs_checkout’, function( $checkout, $context ) {return false;}, 10, 2 );
    
  1. I installed the plugin WP Rollback to rollback some plugins https://wordpress.org/plugins/wp-rollback/
  1. I installed the plugin WP Control to manually run the hooks wp_update_plugins and wp_version_check https://wordpress.org/plugins/wp-crontrol/

Replying to oliverstapelfeldt:

What's the best way to trigger an update for testing?

Last edited 4 weeks ago by JosVelasco (previous) (diff)

#19 follow-up: @oliverstapelfeldt
4 weeks ago

The more I think, what about a place for core, themes and plugins to put a link?
Then the mails could be extended with translatable strings linking there.

#20 in reply to: ↑ 19 @JosVelasco
3 weeks ago

I'm sure there is a way to build the plugin's URL and make it translatable, but let me first ask what should be the best way to go in slack.

Replying to oliverstapelfeldt:

The more I think, what about a place for core, themes and plugins to put a link?
Then the mails could be extended with translatable strings linking there.

This ticket was mentioned in Slack in #core-auto-updates by josvelasco. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #core by afragen. View the logs.


3 weeks ago

#23 @ChrisHardie
2 weeks ago

Following the introduction of the Update URI plugin header field, it seems this could be a good time to introduce a Changelog URI header field.

For purposes of a changelog link in the update notification email, wporg-hosted plugins may be the most common case, but can't be assumed.

We could try to get in to the logic of determining where a plugin's changelog is hosted (perhaps based on where a plugin gets its updates from), but that could get messy pretty quickly. In the long run I'm guessing it will be best to ask plugin authors to specify this information (either in all cases, or as an exception if it is not wporg-hosted).

That would provide a better user experience when the changelog is maintained on an external website, or when there is a changelog section on the wordpress.org plugin's directory page, but it is just a link to an external changelog hosted someplace like GitHub.

If others agree that this header field is a prerequisite to having useful changelog links in update email notifications, I can collaborate with @JosVelasco to open a new ticket and work on a patch proposing that change.

#24 @oliverstapelfeldt
2 weeks ago

Thank you for your support of my idea 🙂

#25 @Ipstenu
2 weeks ago

Why not just use changelog.txt?

readme.txt
license.txt
changelog.txt

Those are all pretty common filenames, and ones people would expect to see for updates.

Making more headers to maintain is long-run difficult, just based on how many people don't update/fully use the existing ones (see people and their lack of updating their tested-up-to). But a changelog file is common outside of WordPress which would let us leverage existing education.

#26 @JosVelasco
2 weeks ago

Thanks @Ipstenu for your comment. I'd love to read an excerpt of the changelog.txt with a "read more" link to the plugin's URI.

#27 @Ipstenu
2 weeks ago

My advice: Keep things as simple for the devs as possible. The more things you make them do, the higher the burden and the LESS likely anyone is to remember it all and keep up. An existing format we automatically pull data reduces the work to pull data remotely (which would be a GDPR issue anyway).

#28 @oliverstapelfeldt
2 weeks ago

Do all themes and plugins have a changelog.txt?

#29 @ChrisHardie
2 weeks ago

I like keeping things simple! :)

Here's the current recommendation from the [Plugin handbook https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#file-size]: "As for your changelog, we recommend keeping the current release in the readme and splitting the rest out out into it’s own file — changelog.txt for example. By storing all the older changelog data there, you keep your readme small and allow the people who get really into long changelogs to read things on their own."

So if we hope and assume that plugin developers (for items hosted on wporg and not alike) are keeping up readme.txt with the most recent changelog entries and changelog.txt with the rest, would it make sense to link directly back to those files on the site itself, within the update notification email?

https://example.com/wp-content/plugins/akismet/changelog.txt
https://example.com/wp-content/plugins/akismet/readme.txt

Or are web hosts likely to be blocking web access to random text files inside plugin directories?

Parsing out the actual contents of the changelog content into the email message body seems like it would be fraught with formatting and sanitizing issues, but I agree it would be nice to see a snippet of it there.

This ticket was mentioned in Slack in #forums by ipstenu. View the logs.


2 weeks ago

#31 @dd32
2 weeks ago

Perhaps the Upgrade Notice field could be included?

The Upgrade Notice field is defined in the readme, and is the text that is shown on the updates page below the plugin.

Few plugins use it right now, but including that if set, and linking off to the WordPress.org page for the changelog tab would make sense to me.

#32 in reply to: ↑ description @ChrisHardie
7 days ago

After discussing further with @JosVelasco today we agreed between us that a useful initial change would be to link, within the notification email body, the name of the plugin that has been updated, using the value of the Plugin URI field, if available.

That should work for wporg and externally hosted plugins alike, doesn't depend on a behavior change by plugin authors or unexplored assumptions, and gives the receiving user an initial option to look for the changelog and get more information. From there we can figure out how to improve the usefulness of the link and/or add additional information.

Unless there are concerns with that approach, we'll work on a patch.

#33 @oliverstapelfeldt
7 days ago

Sorry for not answering!

Thank you for working on a patch! Do you need any help?

This ticket was mentioned in PR #1688 on WordPress/wordpress-develop by ChrisHardie.


45 hours ago

  • Keywords has-patch added; needs-patch removed

This PR adjusts the logic for generating the description of plugins that were updated, or that failed to update, as included in the notification email sent to site admins after an update run has completed.

Specifically, it appends a link to the plugin's main URL (as defined in plugin header metadata fetched by get_plugin_data()) so that a user can track down more information about the plugin, changelog, and support options.

Trac ticket: https://core.trac.wordpress.org/ticket/53049

#35 @prbot
45 hours ago

ChrisHardie commented on PR #1688:

Some example email results for reference:

Success:
https://i0.wp.com/user-images.githubusercontent.com/311772/134176560-da1d1aed-58a8-47bb-915c-4a519b3ee6a1.png

Multiple success:
<img width="1064" alt="Screen Shot 2021-09-21 at 08 47 34" src="https://user-images.githubusercontent.com/311772/134176594-d1deae1c-6d9e-409d-8da1-7ddc3e07c3b8.png">

Fail:
<img width="1051" alt="Screen Shot 2021-09-21 at 08 52 19" src="https://user-images.githubusercontent.com/311772/134176626-96da1d75-f634-469d-a413-167e5a38bc9c.png">

#36 @prbot
39 hours ago

ChrisHardie commented on PR #1688:

Here are some testing steps to generate an autoupdate email on a test site:

  1. Install the WP Rollback plugin (https://wordpress.org/plugins/wp-rollback/)
  2. Install the WP Crontrol plugin (https://wordpress.org/plugins/wp-crontrol/)
  3. Install a third plugin that you can test rolling back / auto-updating.
  4. Roll back the version of the third plugin using the "Rollback" link from the Plugins screen.
  5. Visit Tools -> Cron Events and under "wp_version_check" click "Run Now"
  6. Look for the email notification about the auto-update run, and view the resulting email body

If you are not sure where emails from your test site are going, consider installing a plugin like https://wordpress.org/plugins/wp-mail-logging/ to capture and log them for viewing.

If you're using WP CLI, here's an alternate way to achieve the same testing without using the Rollback or Crontrol plugins.

  1. Install any given plugin to test with: wp plugin install <testing-plugin-slug>
  2. Rollback the plugin: wp plugin update --version=1.0 <testing-plugin-slug>
  3. Make sure auto-updates are enabled: wp plugin auto-updates enable <testing-plugin-slug>
  4. Run the core auto-update cron task: wp cron event run wp_version_check
  5. Look for an email. If nothing, wait a few seconds and re-run the cron task.

This ticket was mentioned in Slack in #core-auto-updates by francina. View the logs.


39 hours ago

#38 @SergeyBiryukov
39 hours ago

  • Milestone changed from Future Release to 5.9

#39 follow-up: @oliverstapelfeldt
39 hours ago

Didn‘t you want to link the name?

#40 in reply to: ↑ 39 @ChrisHardie
39 hours ago

Replying to oliverstapelfeldt:

Didn‘t you want to link the name?

I had forgotten that WordPress sends plain-text emails, which makes sense for maximum compatibility, so I believe a plain-text presentation of the URL will have to do for now.

#41 @oliverstapelfeldt
20 hours ago

What's the best way to trigger an update failure?

Note: See TracTickets for help on using tickets.