[wp-meta] [Making WordPress.org] #5652: Plugin Readme Header Spec Update (was: Plugin Readme Header Spec Upgrade)

Making WordPress.org noreply at wordpress.org
Wed Mar 10 02:14:32 UTC 2021


#5652: Plugin Readme Header Spec Update
--------------------------------------+---------------------
 Reporter:  pewgeuges                 |       Owner:  (none)
     Type:  enhancement               |      Status:  new
 Priority:  normal                    |   Milestone:
Component:  Plugin Directory          |  Resolution:
 Keywords:  has-patch needs-approval  |
--------------------------------------+---------------------
Changes (by pewgeuges):

 * keywords:  has-patch close => has-patch needs-approval


Comment:

 Replying to [comment:7 Otto42]:
 > I'm really not seeing the point of that.

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

 In [comment:4 comment #4] you wrote:
 > Replying to [comment:2 pewgeuges]:
 > > Replying to [comment:1 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 [https://wordpress.org/plugins/readme.txt readme.txt]
 as found at the end of [https://wordpress.org/plugins/developers/#readme
 Developer Information], linked from the
 [https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-
 txt-works/ 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 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 [comment:1 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 [https://developer.wordpress.org/plugins/wordpress-org/detailed-
 plugin-guidelines/#3-a-stable-version-of-a-plugin-must-be-available-from-
 its-wordpress-plugin-directory-page 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 [https://wordpress.org/plugins/developers/readme-validator/ 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`.

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/5652#comment:8>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org


More information about the wp-meta mailing list