[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:  normal            |   Milestone:
Component:  Plugin Directory  |  Resolution:
 Keywords:                    |
------------------------------+---------------------

Comment (by pewgeuges):

 Replying to [comment:4 Otto42]:
 > 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.

 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 this comment.]
 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.]
 }}}

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