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

[Making WordPress.org]

#5652: Plugin Readme Header Spec Upgrade
------------------------------+-----------------------
 Reporter:  pewgeuges         |      Owner:  (none)
     Type:  defect            |     Status:  new
 Priority:  high              |  Milestone:  Q1
Component:  Plugin Directory  |   Keywords:  has-patch
------------------------------+-----------------------
 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.
 1. 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?
   1. 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
 }}}

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