The DOC Directory Requirements | ClassicPress Documentation has an example of readme, it features Requires: 1.4 and Tested: 1.4
These tags are wrong, they must be Requires at least and Tested up to
I have already changed that in the actual DOC introduction, but notice more and more CP plugins featuring the wrong tags.
Has this been defined at some point as the way to go with CP?
If so, where please is the code reading those tags?
Why are we adding custom tags when we expect WP Plugins to work with CP?
By my understanding the only supported tags are Requires at least and Tested up to, and they must be the respectively highest WP version and lowest WP Version (thus, something like Requires at least: 4.9.15 and Tested up to: 4.9.99 for example) .
@joyously you might have more to say to this, probably knowing the readme/plugin headers better than anyone else here.
Fact is, right now it is a blatant mess and I see everything from Requires: 1.0.0 up to Tested: 6.0.
We need to define this asap because we cannot expect Developers to go back and forth changing tiny mistakes we make.
Do we? I think that’s the first thing to decide.
The readme.txt is only used by the WP repo, which is then sent by their API. Any other info in core is parsed from the plugin headers.
I think the code for checking the version numbers has been backported. I’m not positive it’s correct, though. The WP code briefly had a fallback to read the readme file, but that was removed. I think the removal part wasn’t backported…
“Requires” is lowest version that will work. “Tested” is only used on the WP repo page itself, for users to see, and should be highest WP version that was tested. (WP repo only uses the first part x.y and not .z for both of these since it’s not semvar.)
At WP, I advocated that they have a min and max range of versions that a plugin would work with, which could be generated by the Tide framework. But they didn’t go that way.
CP probably needs to have a CP version and a WP version, along with the PHP version. Trying to use the same readme with one extra version number should work okay, right?
Thanks - this all makes sense, but what is the right to use? Requires at least and Tested up to or Requires and Tested?
Because in the WP doc, I see only the first 2 used. I never saw the other 2.
Do you agree that (no matter if we use an .md or .txt, be it for WP or CP at the current moment) we have to use the first 2?
I totally agree about the need of a CP “unique” tag for version tested and required. However I believe this needs code in CP core that isn’t there at the moment, which we probably won’t get anytime soon?
About headers, we have to consider that Update Manager seems to use his own looking at the code here.
I hope not to be requested to change Update Manager for that. It was written by John, it’s coded in a beautiful way and I know pretty well how it works, but I prefer to avoid the risk of breaking something.
My preferred solution is that readme.txt will be abandoned and plugin header will be used for Requires / Requires at least and tested / tested up to.
So now I know why there are those Tested and Requires in several plugins!
It is not that we requested them, it is that the plugin (Update Manager) when it gets integrated in a plugin probably asks for those?
The thing is, tested and requires do not exist in WP or CP by as far I know and saw, ever.
So yes, really, this is an issue.
We cannot go and ask those who already did this to change it (unless where it already happened!)… yet we cannot just invent new tags and call them core-tags either.
So probably you have to add both by now. Because core certainly does not read these tags. Luckily as Joy says, only the WP Repo reads the readme anyway, as it seems. So …
We do have Many WP plugins in CP. We cannot expect them to add new “invented” tags
We do have many CP plugins in CP, some of which use the “invented” tags and some use the “original” tags
My integration I created does not care. It cares only about what the API says, and what WP Function says about “current version” of the plugin, nothing about what it supports
Literally screw it?
I vote for totally removing all readme requirements completely and only require plugin file headers.
The rest, we cannot use in a consistent way anyway, and we clearly have no system behind it either.
So why make developer live complicated if we cannot even give them clear rules (and obviously just did not care about it in past, and happily admitted plugins to do whatever they liked. I mean, it never even came up in years of CP history. So this probably also means it does not matter at all)
And, it’s not surprising that we’re where we are.
One example is this
If we even would have tested we’d know the version doesn’t update on new Release. We’d know what we need (readme txt, readme Md, requires or requires at least etc)
But we’re always saying we’ll look into it and we never do. It’s the same throughout the entire project and almost all tasks ever came up.
I’m diverging from the topic, but let’s do things differently this time.
Let’s look at what works. Then, let’s adapt.
No more “we’ll look into it”
So, what do we have?
The readme is NOT read by WP if the plugin is not stored on WP Repo. This means, in dashboard > plugins you cannot see “view details” for any of those plugins, even if they include a readme.txt or MD.
The Directory itself does NOT read the readme or any of its info. It needs to be added all manually when submitting the plugin (version, minimum required, etc etc)
My new integration does not care about readme, and gets it right nonetheless because it gets info from plugin header and Directory API.
WP or CP core does not care about readme at all
The Directory does NOT read the new release version and automagically update the download URL either. It needs to be manually updated, both, I just tested it.
All in all, readme (be it md or txt) can be ditched completely as requirement since it is simply not helping. No one ever sees it, no code ever uses it, and the only way to see/read it is to go to Git. It is only wasting time of reviewers and developers.
Update Manager asks for those fields in “Plugin Details”, and many people (like me) copy the readme.txt content in that field because the file structure is nearly identical. But that information is stored in the database of Update Manager.
Plugins using UpdateClient.class.php have view details, but data is taken from the server and not from the local readme.txt, so even for that is unuseful.
So for this.
It’s important to know. It’s an extra step in the release process but it’s easy.
But can also easily implemented using GitHub API using tag_name for the version, assets-> browser_download_url for the file or fallback to zipball_url if the developer did not attach the release zip file.
Sorry @joyously i forgot to answer this.
I think we do, yes. Like “what works with wp 4.9 will work with cp” kind of rule I’ve seen around here since I’m using cp.
I’m not for it, but I’m also not seeing any other possibility right now than at least trying this approach.
We also have actually several “works with” plugins that are initially made for wp.
However if we don’t expect readme and weird tags… it’s not a problem for them
So, if we’re going with what @anon66243189 and @Simone have suggested (which sounds good to me), do we need to put Tested up to and Requires at least in the plugin header? Asking for a friend …
Trying to follow this discussion. Are we ditching readme and focusing on plugin headers (and directory API data)?
If CP core isn’t using it and directory isn’t using it, then there’s no reason to require it. WP plugins can continue to add it if they want, but CP guidelines need to be changed.
There wasn’t any reason as of why to use short versions brought up in this thread, or any requirement in general by cp/dir, and long versions are the (wp) right ones to use.
At cp, it doesn’t matter as nothing reads those, and the plugins ain’t breaking if missing. As a matter of facts they aren’t even really required by core.
Today I’m going to do a short technical test on a cp install and then I’m going to update the docs.
If by any time in future we require them, plug-in devs can always add stuff. Missing it isn’t equal vulnerable code, and that’s what we’ve to focus on mostly when it comes to plugins directory.
Thus, unless we can spot a real technical requirement for cp, all sorts of readme are from now on suggested, not required.
Same goes for the (not supported in cp) plugin header tags.
As long your plugin ain’t listed/coming from the WP Repo, the CP does not read the tags at all.
This is because the plugin won’t even appear in the Add Plugins screen, which is the only place this data is read.
In the active plugins screen, the data is not read, at all, whether you put it in the readme or plugin header.
Now, in order to prepare for the future, I have updated the doc as such:
Require statements go into the Plugin header. That is to be precise Requires PHP and Requires at least.
Tested statements go into the Readme (if there is one). That is to be precise Tested up to:
You do not need a .txt readme file, it can be an .md
Currently, you do not need a readme at all from a technical point of view, but we suggest adding either of, because in the end, the dev will want to put some instructions somewhere, and the dev will need to put some license somewhere, which is usually put in the readme (to be precise, that is License:andLicense URI:, the latter only required if the license is not GPL common license but some “compatible” one)
A changelog is suggested to be put in a changelog.txt file, however, again, CP does not read this if the plugin ain’t from WP, so you can as well put it in the readme or omit it. (this is not documented yet, and we do not review it anyway).
#5 Changelog. This is one of the most important parts of a plugin listing in WP repo as it contains a lot of valuable data - what changed, what got fixed, etc. Even though we don’t display them anywhere YET, I think standardizing this process now is important. I have 2 suggestions/options to choose from:
Require devs use CHANGELOG.md to be consistent with Git. We can use it later, if we choose to.
OR Since we require devs to use Releases in GitHub (and other Git platforms), we can simply link to Releases page and ask devs to provide list of changes there. I find this very helpful.
We however can’t require git, currently we require a public repo
That should be git but can be wp svn too.
(This was always the case but actually not properly documented, updated the doc already in regards and also the respective developers)
Otherwise no wp plugin would ever list on our dir (like beaver builder for example, we can’t expect them to run two repos)
So this requirement only would make sense for plugins developed for cp.
I think it makes sense to have the same flow as wp does, that would be a changelog.txt file, but it’s contradictory to git’s standards … so an md would make more sense.
But I’m not sure we should actually force this.
Not yet, anyway. Once we read it, we can invite devs to add it (if missing), and make it required from that point on forward?
We could simply ask for changelog URI, similar to License URI. In addition to Releases page, devs could link to changelog in WP repo, or even to their own website like Beaver Builder does (which is more common with premium plugins): https://www.wpbeaverbuilder.com/change-logs/
So wherever devs keep their changelog, we would have a link to them.
We can strongly encourage them to do it, but not require it (yet).
Being our doc a guideline with required topics, and the review guidelines as well only checking required things, I think we do not need to add it to the “required” parts.
I added a sentence to the review guidelines to check for a changelog and recommend one in case missing
It can be either txt or md.
for this.