Plugin Directory: Add "Requires PHP" header to readme standard

[SergeyBiryukov]

#2952 implemented a Requires PHP header for plugins.

The readme validator currently displays a warning if the header is missing, which is good for the ​ongoing initiative to encourage people to use more recent PHP versions.

The new header should be added to the ​readme.txt example and documented in the Plugin Developer Handbook.

[Otto42]

Additionally: The readme.txt example is currently just an uploaded file to the site using the media system. It should be stored in version control instead. Either through the plugin-directory plugin, or the plugin directory's theme.

[xkon]

Well hello there !

I was thinking as well to continue @Otto42 thought that maybe the readme.txt could be transfered inside the Handbook as well as there is the Header mockup there could be a full readme there as a base to have everything grouped up nice.

If you want it within the plugin as you say would a shortcode be an option? for example [show-plugin-readme-example] that would output what readme.txt currently has? I'm not sure what you mean exactly as even the .txt itself could be added on the version control even.

I've made the proposals on the #docs channel and for now I'm adding the readme.txt up with the change adding the Requires PHP hoping for some replies from the docs team to see how we can get it going with the Handbooks as well.

[xkon]

Adding Requres PHP

[xkon]

As a follow up, the Handbooks have been updated including the Requires PHP ( thanks to @milana_cap ).

​https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/

There have been suggestions on moving / merging the Handbook pages that are about the readme.txt into one place for easier access + maintenance, also updating the page at ​https://wordpress.org/plugins/developers/ to instead linking on the readme.txt file to link on a Handbook page instead about it.

I don't know if you want extra tickets for those :) .

[SergeyBiryukov]

Replying to xkon:

I was thinking as well to continue @Otto42 thought that maybe the readme.txt could be transfered inside the Handbook as well as there is the Header mockup there could be a full readme there as a base to have everything grouped up nice.

Having the readme example under a permanent, non-date-based URL would resolve #3022 as well.

[xkon]

Adding readme.txt under the wp.org Plugins Theme

[xkon]

3123.diff adds the readme.txt ( updated with the Requires PHP as well ) under the wporg-plugins theme in a new folder named files that can host more assets in the future if needed.

Probably this tackles #3022 as well as suggested above.

[SergeyBiryukov]

Apparently the file was already added to the theme in [3442], it's just not referenced anywhere:
sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-plugins/readme.txt@4223​

There was also a change in [3444] to recommend the Markdown format, which went unnoticed.

I think it should probably be moved to the plugin-directory plugin though, since it's not related to the theme, and the theme is not the most obvious location for it.

It would also be nice to create a rewrite rule so that the URL could be https://wordpress.org/plugins/files/readme.txt instead of
https://wordpress.org/plugins/wp-content/plugins/plugin-directory/files/readme.txt

[xkon]

Updates to markdown + plugin-directory

[xkon]

3123.2.diff add the readme.txt into the plugin-directory instead under folder files again and is converted to markdown as well.

As for the rewrite rule we could do this to support all files under the /files directory that might exist in the future

RewriteRule ^plugins/files/(.*)$ /plugins/wp-content/plugins/plugin-directory/files/$1 [R=301,NC,L]

[Otto42]

We can't use RewriteRule's like that. We don't run Apache, we run nginx. Any such URL munging should be done in WordPress, in the relevant plugin code.

[xkon]

Alright @Otto42 thanks for pointing out! Learning something new every 5 seconds here. I'll look into that as well and probably provide a .diff with everything included.

[Otto42]

We're also not converting the readme.txt to another flavor of markdown. That is out of scope for this ticket. I'll likely revert [3444], because it's ridiculous.

[xkon]

readme.txt into plugin-directory

[xkon]

I'm adding a partial 3123.3.partial.diff to get the readme.txt back to the normal one as Otto said above with the Requires PHP, while adding it into the plugin-directory folder, but my mind doesn't want to achieve the rewrite rules at the moment.

I've gotta run to work but will get back to it later on today as well if nobody else has already.

[xkon]

readme.txt to vcs proposal

[xkon]

Ok after giving it a lot of research on getting to read something under the plugins folder without making it work I decided to propose the way I'd do it without an actual 'url rewrite'.

This way in 3123.4.diff we achieve all of the above as well.

1) We include it on the version control.
2) It adds a custom template to /plugins/readme.txt to show readme.txt's contents.

I know that this goes off from what @SergeyBiryukov suggested on getting it into the plugin, but it does the job or at least it's a start I think with everything needed here.

What I simply did is added a plugin-readme-txt.php file within the wporg-plugins template and created a custom function to show that file when someone goes to /plugins/readme.txt. It's a basic html template nothing more to it.

I've tested this on a normal template but I'm at work without access to VVV so if you can test it it'll be awesome.

---

Edit:

Testing in VVV now and apparently this doesn't work since everything under /plugins/ trigger a search instead. Going back at it now that I have VVV at least I can test. Sorry for all the spam ! Trying hard here..

[xkon]

Added into plugin-directory with a redirect

[xkon]

3123.5.diff addresses everything ( I think ) after a long day of researching VVV and learning so I'm happy and I think this is ready for a final review.

• Adds a redirect on /plugins/readme.txt to read the file contents.
• readme.txt is added into vcs now in the \files\ folder of the plugin-directory
• readme.txt has the Requires PHP as well

[xkon]

using text/plain

[xkon]

After reading the slack chat on #meta since I was not able to be there yesterday ( sorry ! ) I saw some concerns for <pre>. In 3123.6.diff I changed <pre> into using text/plain instead as suggested to avoid validation issues that might rise.

[obenland]

@Otto42 What do you think of 3123.6.diff​?

[Otto42]

In 6392:

Plugins: Point to new readme.txt file to add Requires PHP line, see #3123

[Otto42]

The addition of the rewrites makes sense if we're going to use the one in the theme, rather than the one we maintain in the WordPress media library right now. Especially since when I updated it, the date changed so I had to alter the theme anyway.

[obenland]

In 6411:

Plugins: Move example readme file to plugin.

Gives the file a version history and makes it available from the Plugin Directory root.
It also removes the need to update the URL every time a new version gets uploaded.

Props xkon.
Fixes #3123.

[dd32]

In 8587:

Plugin Directory: https://wordpress.org/plugins/readme.txt should return a 200, not 404.

See #3123.