Making WordPress.org

Opened 3 years ago

Last modified 3 years ago

#5652 new enhancement

Plugin Readme Header Spec Update

Reported by: pewgeuges's profile pewgeuges Owned by:
Milestone: Priority: normal
Component: Plugin Directory Keywords: has-patch needs-approval
Cc:

Description

The WordPress plugin readme.txt specification at https://wordpress.org/plugins/readme.txt is janky and should be upgraded to a state-of-the-art one. Explanations in https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/ are unable to palliate the defective specification.

The plugin readme has two main defects:

  1. It is parsed for release configuration. Readmes are not the place to store such information; these files are for people to read, not for machines to parse.
  2. It is lacking important information:
    1. The Package Version has been moved to the main PHP file. That is not the appropriate place either. All version numbers should be found in a single place, not in two places. That single place is the readme. PHP scripts cannot be accessed. Or was the purpose to hide the package version from the public?
    2. The Tagged Version is missing completely. For the Stable Tag to make sense, i.e. not to be pleonastic, the most up-to-date (latest) tag may be ahead of the stable tag. As-is, WordPress imposes the immediate release of all bugfix versions. Projects may wish to make bugfixes available as regular versions, as opposed to distributing unreliable and ephemeral development versions out of trunk/, while refraining from overwhelming the Community with continuous (or at least not spaced-out enough continual) releases.

The unexpected and counter-intuitive parsing of the Stable Tag in readme.txt as if it was in a configuration file requires a comment line immediately below the Stable Tag field.

The suggested upgraded WordPress plugin readme header is in full:

=== Plugin Name ===
Contributors: [comma-separated]
Tags: [comma-separated]
Requires at least: [WordPress version]
Tested up to: [WordPress version]
Requires PHP: [version]
Package Version: [plugin version]
Tagged Version: [plugin version]
Stable Tag: [plugin version]
CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION.
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Attachments (2)

readme.txt (4.5 KB) - added by pewgeuges 3 years ago.
with new header as suggested (edited for attachment), provided as a patch ('has-patch').
readme.2.txt (4.5 KB) - added by pewgeuges 3 years ago.
License corrected from GPLv3 to GPLv2.

Download all attachments as: .zip

Change History (14)

#1 follow-up: @Otto42
3 years ago

  • Keywords has-patch removed
  • Milestone Q1 deleted
  • Priority changed from high to normal

The moment we add explanatory text in the example is the same moment when the plugin review team will start seeing it in submitted plugin's readme files.

We already recognize elements of the example file and use that to determine when plugin authors aren't paying attention, and thus use that information to better help support them and their submitted plugins. Changing it is more than just "changing it".

#2 in reply to: ↑ 1 ; follow-up: @pewgeuges
3 years ago

Replying to Otto42:

The moment we add explanatory text in the example is the same moment when the plugin review team will start seeing it in submitted plugin's readme files.

That’s cool, thanks. Implies that it’s safe to add this needed extra information in the header.

We already recognize elements of the example file and use that to determine when plugin authors aren't paying attention, and thus use that information to better help support them and their submitted plugins. Changing it is more than just "changing it".

No doubt that changing the readme header spec requires emailing all plugin committers.

I see a problem though: How will submitting plugins with extended readme headers be going to happen as long as WordPress seems to restrain these headers to the available template with spec status?

#3 @pewgeuges
3 years ago

@Otto42

The Plugin Review Team starting seeing the 3 added lines in submitted plugins’ readme headers is the expected outcome.

Your convoluted and sibylline response resulted IMO from a lack of precision in the ticket description as I posted it.

If the permission to add custom fields in the plugin readme header can be inferred from https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#custom-sections without overstretching the allowance for custom sections in the readme body, then why not add these to the spec since the Package Version and Tagged Version are useful information. This information needs to be provided in a place that users can be expected to look up, and that can be accessed remotely. If hiding this information is intended, that should be stated in the spec.

As of the comment line, it has become indispensable in Footnotes’ readme header after v2.5.10, and it needs to be in all caps there, while other projects may use lowercase; they may drop it only if they can guarantee being maintained by professionals long-term.

#4 in reply to: ↑ 2 ; follow-up: @Otto42
3 years ago

Replying to pewgeuges:

Replying to Otto42:

The moment we add explanatory text in the example is the same moment when the plugin review team will start seeing it in submitted plugin's readme files.

That’s cool, thanks. Implies that it’s safe to add this needed extra information in the header.

I think you misread what I meant.

If we change the example to have "CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION." in it, then what we're going to get is readme's that have that exact text in it. Unchanged.

If we put "Stable Tag: [plugin version]" then we will get people asking why their ZIPs have [plugin version] in it. And similar.

People don't make changes where you want them to make those changes. We get submitted plugins with "=== Plugin Name ===" in them all the time, because people don't put their plugin name in the first line of the readme file.

So explanatory text will be ignored and people will simply submit it with that text there. Your approach, while understandable, doesn't seem like a thing that will work to me.

#5 in reply to: ↑ 4 @pewgeuges
3 years ago

Replying to Otto42:

Replying to pewgeuges:

Replying to Otto42:

The moment we add explanatory text in the example is the same moment when the plugin review team will start seeing it in submitted plugin's readme files.

That’s cool, thanks. Implies that it’s safe to add this needed extra information in the header.

I think you misread what I meant.

Later I was told that I did. Then I realized that no-one got the point of actually shipping the “CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION” warning in released plugins, unless a publisher thinks it’s safe to remove it. Basically it is not safe to remove it, see https://meta.trac.wordpress.org/ticket/5645#comment:2

This warning comment line in all-caps plus the presence of the to-be-added Package Version field will eliminate any risk of accidental releases of development versions, as it happened also to me on November 2, 2020.

The spec (https://wordpress.org/plugins/readme.txt) assumes and urges to always immediately release the most up-to-date tag. In that use case, Stable Tag === Tagged Version. But a project frequently providing timely bugfix versions, as it happened on Footnotes, may need to refrain from keeping doing so after an accidental release of a broken development version taking entire websites down.

That’s where the Stable Tag starts making actual sense as being the stable tag, as opposed to bugfix versions available for manual installation.

Also, in https://meta.trac.wordpress.org/ticket/5645#comment:4, @Ipstenu warned about a bug occurring when Stable Tag > Version. Such mishaps would not happen if the Version field was moved to the readme header where the Stable Tag field resides. That is a warning example how parsing TWO file headers for configuration information screws things up.

If we change the example to have "CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION." in it, then what we're going to get is readme's that have that exact text in it. Unchanged.

That is indeed the expected outcome. When I wrote about a “comment line” and added it in the patch intended to upgrade the spec, the suggestion was about everybody seeing this line when reading a plugin readme, and mistakenly editing this field would never happen again in the WordPress ecosystem.

If we put "Stable Tag: [plugin version]" then we will get people asking why their ZIPs have [plugin version] in it. And similar.

If that happens, then I should have left the template as-is.

People don't make changes where you want them to make those changes. We get submitted plugins with "=== Plugin Name ===" in them all the time, because people don't put their plugin name in the first line of the readme file.

If you are getting this all the time, then replacing the “Plugin Name” placeholder with something like “[Please put here your plugin’s name and delete this comment.]” might fix the problem. Did you already try that out?

So explanatory text will be ignored and people will simply submit it with that text there. Your approach, while understandable, doesn't seem like a thing that will work to me.

As mentioned, for the added comment line that’s really fine. Not for the rest, though.

May you please take a look at this template to see if it would work out better?

=== [Please put here your plugin’s name, and delete this comment.] ===
Contributors: [Please put here a comma-separated list of all who contributed to your plugin, and delete this comment.]
Tags: [Please put here a comma-separated list of keywords, and delete this comment.]
Requires at least: [Please put here the lowest WordPress version your plugin works with, and delete this comment.]
Tested up to: [Please put here the highest WordPress version you have tested your plugin with, and delete this comment.]
Requires PHP: [Please put here the minimum PHP version your plugin works in, and delete this comment.]
Package Version: [Please put here your plugin’s package version and delete this comment.]
Tagged Version: [Please put here your plugin’s latest tag folder name and delete this comment.]
Stable Tag: [Please put here the name of the tag folder used for current download, and information, and delete this comment.]
CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION. [Please be careful about the value of this field in trunk/ because this information is parsed in the readme in trunk/, and delete the bracketed part of this comment line.]
License: GPLv3 or later [Please replace this with your plugin’s license if it’s released under another one, and delete this comment.]
License URI: https://www.gnu.org/licenses/gpl-3.0.html [Please update this URL as needed, and delete this comment.]
Version 1, edited 3 years ago by pewgeuges (previous) (next) (diff)

@pewgeuges
3 years ago

with new header as suggested (edited for attachment), provided as a patch ('has-patch').

#6 @pewgeuges
3 years ago

  • Keywords has-patch added

#7 follow-up: @Otto42
3 years ago

  • Keywords close added
  • Type changed from defect to enhancement

I'm really not seeing the point of that. For one, that is a horribly ugly example to me. But mainly, we have plenty of existing documentation.

Every plugin developer gets an email when their plugin is just created that links to all of our documentation, including the documentation on how to make a readme properly.

We do expect them to read and know this information. All the details that you are adding to the example file are documented already.

I believe this sort of overabundant explanatory text is unnecessary, and ultimately harmful to the plugin review team as well as to the directory and the ability of authors to properly understand the desired content of the readme.txt file.

To me, this seems like a close with wontfix. My 2 cents.

#8 in reply to: ↑ 7 @pewgeuges
3 years ago

  • Keywords needs-approval added; close removed
  • Summary changed from Plugin Readme Header Spec Upgrade to Plugin Readme Header Spec Update

Replying to Otto42:

I'm really not seeing the point of that.

That’s due to me repeatedly failing to convey the point.

In comment #4 you wrote:

Replying to pewgeuges:

Replying to Otto42:

The moment we add explanatory text in the example is the same moment when the plugin review team will start seeing it in submitted plugin's readme files.

That’s cool, thanks. Implies that it’s safe to add this needed extra information in the header.

I think you misread what I meant.

I did misunderstand you. For a short while I scrambled to make sense, then I read that you decided to wait with adding explanatory text in the template until the Plugin Review Team sees it in submitted plugins, as sort of a proof of concept, since that’s precisely what we’re trying to do, i.e. it needs to be in Footnotes’ readme.txt. So I thought you were waiting for this POC before adding the new lines to the spec.

And as expressed in reply, I welcomed WordPress’ pragmatic approach watching from the sidelines how things evolve, then importing novelties in the specification as they seem useful or prove successful.

I didn’t suspect that you didn’t get the point, given there is a point. IMO there’s a very good point. Please give me another try.

For one, that is a horribly ugly example to me.

As already mentioned, it’s actually a template with spec status. To see examples we can look up other plugins. We even need to, because many of them show best practice.

The official name of readme.txt as found at the end of Developer Information, linked from the Plugin Readmes page of the Plugin Handbook, is WordPress plugin readme file standard.

As this is a standard, WordPress is not expected to provide a nice-looking example instead.

But mainly, we have plenty of existing documentation.

Obviously the existing documentation has hidden defects, since admittedly and reportedly it does not work out as expected:

In comment #4 you wrote:

People don't make changes where you want them to make those changes. We get submitted plugins with "=== Plugin Name ===" in them all the time, because people don't put their plugin name in the first line of the readme file.

So explanatory text will be ignored and people will simply submit it with that text there.

Based on your testimony, I’ve changed the suggested field values and now suggest that you explicitly urge plugin authors to replace the bracketed comments with their actual data.

If you get submitted plugins with "=== Plugin Name ===" in them all the time, you are even less sure that the “Requires PHP” version is correct, that the “Requires at least” WordPress version is correct, that the “Tested up to” WordPress version is correct, and also that the license information is correct.

Instead of providing a template coming with predefined values that—according to your testimony—end up being misused as false claims in fake readme headers, you should rather provide a form with blanks to fill in, and with prompts to not leave blanks (nor fake data).

In comment:2:ticket:5645 @dd32 and @rumperuu wrote:

Replying to dd32:

in short it was due to me not realising that changing the ‘Stable Tag’ field to the development version (2.5.9d1) in trunk/readme.txt would cause the WP Plugin Directory to parse it as a new version, look for the corresponding tags/2.5.9d1/ and, upon failing to find it, revert to trunk/.

May I ask, what did you expect would be the result of this? For simply no change to occur?
(Do read on, I'm actually okay with that behaviour and it's something that's been discussed not-on-trac)

I didn't expect the versioning info in readme.txt to have any effect, just as the version number in the Plugin base file docblock doesn't (https://plugins.svn.wordpress.org/footnotes/trunk/footnotes.php). Coming from a string of Node.js projects, I expect I assumed the only important version number was stored in some sort of config file like package.json or composer.json, or that trunk/ was for dev. versions and tags/* was for releases (as this is how this particular Plugin is laid out, but I see that there is no necessity for other projects to use tags).

This behaviour is mentioned in the Plugin Handbook (https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#how-the-readme-is-parsed), but only as a one-liner in the second paragraph of the section of how readme.txt is parsed. Not realising that trunk/readme.txt would be parsed in trunk/, I didn't think to look at how it might be parsed.

but I'm willing to bet that I'm neither the first nor the last person to make such a mistake.

You're definitely not the first, there's been a few cases where larger plugins have had the same thing happen, where trunk was packaged as the tag didn't get committed in the proper format.

To mitigate these issues and lower the risk close to zero, WordPress simply needs to add the Package Version field above the Stable Tag, and the warning below the Stable Tag.

Adding these two lines in standard plugin readmes is strongly recommended.

The Tagged Version field is needed in plugins that cannot release every bugfix version while being committed to fix bugs ASAP after they’ve been reported, and to make the bugfix versions available to the reporters.

Per Guideline #3, WordPress prohibits making bugfixes available elsewhere. e.g. on GitHub.

As a consequence, the plugin readme should include the Tagged Version field, for versions ahead of the Stable Tag made available without immediate release, to avoid overwhelming the Community with too frequent releases.

Do you see the point in adding these 3 lines to the readme template?

Every plugin developer gets an email when their plugin is just created that links to all of our documentation, including the documentation on how to make a readme properly.

An incomplete readme lacking the package version and some other information found only in the plugin’s root PHP file header is not a proper readme. The need of adding the Package Version right in the readme header has been pointed when this ticket was opened, but it was persistently ignored because the point was not clear enough. Hopefully it is, now.

The Readme Validator does not actually validate readmes, it only runs a series of checks, while not allowing to preview the parsed data. Symptomatically it never displays any message like “Your readme is valid!”.

The readme parser’s source code seems inaccessible. The string 'stable tag' is found nowhere in a WordPress instance outside of readmes, so the WordPress blog engine seems unable to parse it.

Where can the code of the Plugin Directory be accessed please?

We do expect them to read and know this information. All the details that you are adding to the example file are documented already.

And you yourself have been hinting that they’re not documented sufficiently, as you stated—summing it up—that the existing documentation does not work out as expected.

I believe this sort of overabundant explanatory text is unnecessary,

You are putting the blame on plugin authors?

and ultimately harmful to the plugin review team

The opposite is true: You will stop getting submitted plugins whose readmes start with === Plugin Name ===. And similar.

as well as to the directory

The only “harm” done to the Directory is the fact that the “already” existing documentation needs an update to enhance efficiency.

and the ability of authors to properly understand the desired content of the readme.txt file.

The desired content is specified in the new bracketed comments.

When you just put === Plugin Name ===, authors are reportedly (you are the reporter) unable “to properly understand the desired content of the readme.txt” heading. That blows up any argument made to maintain the status quo.

To me, this seems like a close with wontfix. My 2 cents.

I’ve replaced the close keyword with needs-approval. You may wish to add other workflow keywords like 2nd-opinion or needs-design-feedback.

#9 follow-up: @dd32
3 years ago

I don't personally see the need for adding extra headers here to be used as validation that the value is right.

The way I'm reading this is:

Stable Tag: 1.2.3
No, What's your "stable tag"?: 1.2.3
Are you sure? What's your actual version you want released?: 1.2.3

There's also some misunderstandings around how WordPress.org plugin versions are handled, WordPress.org is not a perfect system, infact, it's actually very bad, you really only have 1 version that is the current one for download and that's it, you have the ability to tag older releases, have a development version in trunk, etc, but it's not really used at all the way many would do so elsewhere.
WordPress.orgs plugin system is intentional in that, it's migrated away from being a central platform for developing plugins, to a "upload your latest plugin release" and that's it.

I don't think anyone is going to say "The implementation of the Stable Tag header is perfect", but I don't think this solution is actually a solution that's worth investing in.

Instead, I personally think we're better off with the direction of removing the reliance upon the field entirely, dropping support for it effectively, through something like #5484.

This ticket should closed as wontfix IMHO, but I'm not going to mark it as such to allow discussion from anyone else without it being re-opened again. I'll close it if it's still open in a few months time instead.

#10 in reply to: ↑ 9 @pewgeuges
3 years ago

@dd32,

You don’t seem to have got the point either, in spite of the details posted above. Look:

Replying to dd32:

I don't personally see the need for adding extra headers here to be used as validation that the value is right.

Only you are inventing the concept of validating that the value is right. In the examples above, the use case of every field having a different version number may also occur:

Package Version: 1.2.4d0
Tagged Version: 1.2.3
Stable Tag: 1.2.0

Let’s say that 2 days after the last minor version release, a new bug occurring when plugin XYZ is used alongside was quickly fixed in v1.2.1 and made available to the reporter as well as to the Community monitoring the Support Forum. Same for v1.2.2 and 1.2.3. Then, an experimental feature is made available in trunk/ as v1.2.4d0. Later on, it might make it into v1.3.0:

Package Version: 1.3.0
Tagged Version: 1.3.0
Stable Tag: 1.3.0

Note that this is a particular situation occurring at release time.

The way I'm reading this is:

Stable Tag: 1.2.3
No, What's your "stable tag"?: 1.2.3
Are you sure? What's your actual version you want released?: 1.2.3

Sorry for not providing the example before. I didn’t suspect that “changing the ‘Stable Tag’ field to the development version (2.5.9d1)” would not help you understand that this accident would have been prevented if we had a Package Version field so the Stable Tag wouldn’t be mistaken and used for the package version by lack of anything close to a version number as you will find in whatever state-of-the-art readme header.

Package Version: 2.5.9d1
Stable Tag: 2.5.8
CAUTION: THE S. T. FIELD IS PARSED FOR RELEASE CONFIGURATION.

There's also some misunderstandings around how WordPress.org plugin versions are handled, WordPress.org is not a perfect system, infact, it's actually very bad, you really only have 1 version that is the current one for download and that's it, you have the ability to tag older releases, have a development version in trunk, etc, but it's not really used at all the way many would do so elsewhere.

We have the ability to download every single tag plus trunk/ under the Advanced tab. What you are telling doesn’t make sense to me and I wonder about the alleged misunderstanding. Why should the blog engine offer older versions in the plugin catalogue? I think it’s enough to be able to download the *.zip and upload it to the blog for installation whenever an older version is desired.

WordPress.orgs plugin system is intentional in that, it's migrated away from being a central platform for developing plugins, to a "upload your latest plugin release" and that's it.

That’s very bad news. WordPress already advises to delete older versions, which is bad. It works very well for developing plugins without an excessively atomic commit history. Normally, development versions are committed only either to share on the Forum or for pre-release testing, or eventually for traceability to avoid too mixed-up changesets.

I don't think anyone is going to say "The implementation of the Stable Tag header is perfect", but I don't think this solution is actually a solution that's worth investing in.

You don’t need to invest a single cent. Instead, you’re expected to add the Package Version field and the CAUTION warning, plus the optional Tagged Version field. That’s all. As of the fill-in-the-blanks instructions, you may ditch them if you can’t see the point, and if you want the PRT to keep being bothered with reviewing mislabeled plugins.

Instead, I personally think we're better off with the direction of removing the reliance upon the field entirely, dropping support for it effectively, through something like #5484.

You should maintain the stable tag, or we won’t be able to have tagged versions without releasing every single one in the wake. See above.

In comparison, #5484 seems like a rather bad “good idea”. You need to commit to trunk/ anyway. Why not do the release “in one go” as designed in Using Subversion.

This ticket should closed as wontfix IMHO, but I'm not going to mark it as such to allow discussion from anyone else without it being re-opened again. I'll close it if it's still open in a few months time instead.

You primarily need to upload the new attachment (license corrected to GPLv2) to https://wordpress.org/plugins/readme.txt

@pewgeuges
3 years ago

License corrected from GPLv3 to GPLv2.

#11 follow-up: @dd32
3 years ago

Right, I misunderstood you a bit. Some of my reply is relevant though.

I still disagree with the intention of this ticket though.

#12 in reply to: ↑ 11 @pewgeuges
3 years ago

@dd32,

The relevant part of your reply is about #5484, but the click-and-release button automation still relies on parsing the Stable Tag.

To dismantle the danger originating from the Stable Tag, you just need to make it more intuitive by adding a field for the package version in case it differs, and a warning to raise awareness that the unconcerned readme is actually a configuration file, to the attention of developers joining in from other backgrounds. WordPress relies on volunteers, so please make it a bit less unwieldy and more intuitive for newcomers hurrying to help out while engaged elsewhere.

What is the cost for you and the PRT/PD when updating the WordPress Plugin Readme Standard?

Replying to dd32:

I still disagree with the intention of this ticket though.

Would you please elaborate upon your disagreement, please?

Note: See TracTickets for help on using tickets.