Make WordPress Core

Opened 3 years ago

Closed 2 years ago

Last modified 2 years ago

#53049 closed enhancement (fixed)

Add changelog release notes to auto update email notifications

Reported by: josvelasco's profile JosVelasco Owned by: davidbaumwald's profile davidbaumwald
Milestone: 6.1 Priority: normal
Severity: minor Version:
Component: Upgrade/Install Keywords: has-patch has-unit-tests dev-feedback commit
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 (62)

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


3 years ago

#2 @pbiron
3 years ago

  • Component changed from Mail to Upgrade/Install

#3 @pbiron
3 years 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
3 years 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.


3 years ago

#6 in reply to: ↑ 4 @francina
3 years 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 3 years ago by francina (previous) (diff)

#7 @francina
3 years ago

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

#8 @francina
3 years ago

  • Keywords needs-patch added; needs-design removed

#9 follow-up: @oliverstapelfeldt
3 years 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
3 years 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
3 years 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.


3 years ago

#13 in reply to: ↑ 11 @JosVelasco
3 years 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
3 years ago

Do you try?

Meanwhile I think of further questions to be discussed.

#15 @JosVelasco
3 years 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
3 years ago

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

#17 in reply to: ↑ 16 @JosVelasco
3 years 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 3 years ago by JosVelasco (previous) (diff)

#19 follow-up: @oliverstapelfeldt
3 years 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 years 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 years ago

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


3 years ago

#23 @ChrisHardie
3 years 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
3 years ago

Thank you for your support of my idea 🙂

#25 @Ipstenu
3 years 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
3 years 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
3 years 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
3 years ago

Do all themes and plugins have a changelog.txt?

#29 @ChrisHardie
3 years 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.


3 years ago

#31 @dd32
3 years 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
3 years 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
3 years 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.


3 years ago
#34

  • 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

ChrisHardie commented on PR #1688:


3 years ago
#35

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">

ChrisHardie commented on PR #1688:


3 years ago
#36

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.


3 years ago

#38 @SergeyBiryukov
3 years ago

  • Milestone changed from Future Release to 5.9

#39 follow-up: @oliverstapelfeldt
3 years ago

Didn‘t you want to link the name?

#40 in reply to: ↑ 39 @ChrisHardie
3 years 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 follow-up: @oliverstapelfeldt
3 years ago

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

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


3 years ago

#43 @audrasjb
3 years ago

  • Milestone changed from 5.9 to 6.0

As this ticket is an enhancement, and since we're close to WP 5.9 Beta 1, let's move this ticket early in the next cycle.

#44 follow-up: @oliverstapelfeldt
3 years ago

I was at testing, what's the best way to trigger an update failure?

#45 in reply to: ↑ 44 @JosVelasco
3 years ago

I exactly don't know but you could use a commercial plugin that doesn't connect to wordpress.org.

I believe @ChrisHardie has more experience with this. Also, I think we should start to include the plugin's URL only to those hosted on wordpress.org anyways. Can you take a look at this @ChrisHardie?

Replying to oliverstapelfeldt:

I was at testing, what's the best way to trigger an update failure?

Version 0, edited 3 years ago by JosVelasco (next)

#46 @Presskopp
3 years ago

#54594 was marked as a duplicate.

#47 @peterwilsoncc
2 years ago

  • Keywords needs-patch added; has-patch removed

I added some notes to the linked pull request yesterday. It needs some internationalisation improvements but generally looks sound.

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


2 years ago

#49 @afragen
2 years ago

  • Milestone changed from 6.0 to 6.1

This one seems very close but since 6.0 beta1 is today, let's see if we can get done for 6.1.

#50 in reply to: ↑ 41 @pbiron
2 years ago

Replying to oliverstapelfeldt:

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

Sorry for not seeing your question earlier.

The way I generally do it is create a simple plugin that does something like:

add_filter(
    'upgrader_pre_install',
    function() {
        return new WP_Error( 'fake_update_error', 'upgrader_pre_install' );
    }

Depending on what you're specifically trying to test with a failure, you can also hook into upgrader_post_install or upgrader_clear_destination (and there a few other hooks as well).

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


2 years ago

This ticket was mentioned in PR #3100 on WordPress/wordpress-develop by costdev.


2 years ago
#52

  • Keywords has-patch has-unit-tests added; needs-patch removed

This PR refreshes #1688 with changes requested by @peterwilsoncc and adds PHPUnit tests.

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

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


2 years ago

#54 @costdev
2 years ago

  • Keywords dev-feedback added

Per the discussion in the bug scrub, pinging @SergeyBiryukov and @audrasjb for their insights on a possible i18n issue on PR 3100

#55 follow-up: @audrasjb
2 years ago

As said in the PR, the change looks good to me, speaking in terms of i18n / polyglots best practices :)

#56 in reply to: ↑ 55 @peterwilsoncc
2 years ago

  • Keywords commit added

Replying to audrasjb:

As said in the PR, the change looks good to me, speaking in terms of i18n / polyglots best practices :)

Thank you for confirming that, I've marked this ready for commit with the linked pull request.

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


2 years ago

#58 @davidbaumwald
2 years ago

  • Owner changed from josvelasco to davidbaumwald
  • Status changed from assigned to reviewing

#59 @desrosj
2 years ago

@peterwilsoncc to clarify, are you looking to commit this? Or are you letting another committer own this?

#60 @davidbaumwald
2 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 54212:

Upgrade/Install: Add plugin URL to the automatic update email.

For each automatic plugin update, both successful and failed, information about each plugin is included in the email upon completion of the process. This change adds the plugin URL, if known, to the information included for each plugin that was processed.

This change also adds unit tests to validate the email contents after various automatic plugin update scenarios.

Props JosVelasco, pbiron, oliverstapelfeldt, ChrisHardie, Ipstenu, dd32, peterwilsoncc, audrasjb, costdev.
Fixes #53049.

Note: See TracTickets for help on using tickets.