Format plugin description

[xxsimoxx]

When inserting a new plugin there is a field where you can paste your readme.txt

Full Description of Software (you might like to paste the contents of your readme.txt file here)

This should be formatted when this field is displayed.

Maybe you can take the code from CodePotent Update Manager : https://github.com/xxsimoxx/codepotent-update-manager/blob/master/classes/Parsedown.class.php https://github.com/xxsimoxx/codepotent-update-manager/blob/master/includes/functions.php

[KTS915]

1. Looks like we're going to be asking for a readme.md file instead.
2. I have modded the Software Submission Form to temporarily upload the zip file from the URL so as to be able to find the slug programmatically instead of relying on manual input into the form, so it should be possible to parse the readme file for more than just that and the content of the file, but also the headers.
3. PR welcome!

[KTS915]

Actually, I think we can just add the Parsedown.php file from this repo as an mu-plugin, and then do this:

    $Parsedown = new Parsedown();
    $Parsedown->setSafeMode(true);
    $description = $Parsedown->text(sanitize_textarea_field( wp_unslash( $_POST['description'] ) ) );

At the moment, this is still relying on manual copying of the readme.md file, so need to work out how to parse it programmatically instead from the download link URL.

[xxsimoxx]

I've a proof of concept branch here that uses full plugin description with the content of that field being like a readme.txt. It works only for plugins.

Can't do a real PR because it involves much CSS, theme knowledge and jQuery.

It uses some code from Update Manager. More can be done when a decision on which file to use and header fields is taken.

[smileBeda]

Looks like we're going to be asking for a readme.md file instead.

Keep in mind that if you rely on a MD file, you have to force the devs to follow rules and to have all existing plugins update with a readme, which is not the case in all existing plugins yet.

WP has done an amazing job in hammering the format of a readme TXT file in everyones' head, so you can bet that if there is a readme.txt it follows the guidelines. That is not the case for md files, unfortunately dev's put all sorts of stuff in there from header images to status badges in the first lines.

In my updater plugin, I am expecting that at least the first line of the Plugin md file is a # Plugin Name followed by an empty line. That allows me to fall back to it if the readme TXT is missing or malformed. It has proven a huge challenge to get that right and I could not avoid some rule the least, because as said, the formats are just too many. Also because the MD file is shown on Git as the "first thing" and often devs want to show some nice stuff on the MD file... rather than a dry "readme" that is machine ready.

So for me, the readme TXT actually has proven very useful when pulling from GIT, for the reason that it is already very commonly followed in the format, and really has the needed data in the first lines. Also remember that no WP Plugin will add an MD file just because we require it (And we have a number of WP Plugins in CP (for example beaver Builder) ).

Thus, I would suggest revisiting the idea of expecting an MD, and check the way my integration does it, which expects either or, giving priority to the long established readme TXT File which is in 99% of all plugins already present, be it in git or WP SVN.

[xxsimoxx]

From what I wrote on slack earlier...

I’ve elaborated my ideas about the choice of readme.txt etc…

• my choice Use readme.txt standard but don’t require it to be in the repo or zip file. This can just live as the content of the custom post type of the directory. This way a developer can differentiate the content from WP and CP without having different plugin versions. This implies that a dev can access his post in the directory and change it. This is how it’s done in Update Manager. It keeps tabbed information as we have in modal. Look at my horrible test done here: https://dir.educatorecinofilo.dog/plugins/under-construction/
• another option Use README.md but including header information as it’s done here. Look at the raw file here to understand my idea.

[smileBeda]

I like your thing with the hidden meta data! Easily parseable by code and not uglyfying the readme.

what’s needed however in this case is major force to have people following this standard.

Bu I like this md standard proposal a lot.

[KTS915]

Whatever we do, devs are going to have to supply additional information in comparison to what they do for WP. Specifically, they are going to need to specify the minimum version of CP required to run their plugin, theme, or code snippet. (We can take the current version of their software by parsing the URL from the download link.) Having read all the discussion and pros and cons of different methods, requiring a readme.md file seems the least onerous for devs and, as mentioned above, its creation is encouraged by GitHub.

[smileBeda]

I agree, @KTS915 - but that means we will effectively remove all WP plugins who are not willing to go to GitHub from the directory, if I understand right. For someone who develops for WP (but keeps compatible with CP) that additional step can just be the step to say "ok then I ditch it". For someone who already established their Readme md in GitHub, it means going back and re-adapting it. All that while 99% of the plugins already have a readme TXT incorporated since it is deeply rooted in the process of creating a plugin.

I think we should make it as easy as possible for existing software developers to keep going with what they have. Of course, someone developing for WP has their plugin listed there and users can get it though the admin, but it will not be listed as such on the CP Dir, which might just be not ideal. Many (all, actually) plugins listed on github do not follow any rule in Md, but all rules of WP in the txt file.

That means all existing CP plugins will have to go and update their readme md with whatever format we come up with.

It is true that the sooner this is done (as a rule in CP) the better... but I do not believe that it is encouraging for developers. We unfortunately took over a WP "ecosystem" with an established readme structure and I believe - both from experience and from what I foresee happening - that the readme txt will be much easier to enforce than the MD.

This is why in my plugin I just support both, giving txt the priority so the md has its time to evolve - once it is "well adapted" I can always swap the priority or even ditch the txt check. That can encourage the dev's to match the requirements of the MD without a disrupting "change of rules"

I am quite sure that requiring an md in a specific format and listening/reading only that file will cause several plugins if not most to be disappearing from the directory from one day to the other.

I am in total support of an MD requirement/ditching txt, I just do not see that happening anytime soon without losing a good number of authors, I fear, if we do not do it in a "phased" way or in other words, supporting both at least for a certain time.

For "supported CP version", I agree this data is needed, however we do not even have a Plugin header tag for it, and that is actually what will be used by core when activating, not the API information. So the best here would rather be that the developer checks in his plugin the version of CP and aborts activation if not met (of course, it will be nice to have that in the API, but not required for its functionality, as it works without right now as well.)

[KTS915]

I think we can keep all those plugins in the CP repo that are already there. But we need to establish a new standard asap.

We could use the readme.txt file as a fallback, but we'll still probably be missing the minimum CP version. I suppose we could leave this as a field in the submission form that could be filled manually, but it won't get updated as the software gets updated.

[KTS915]

In fact, we don't really need the README.md file included in the software zip file. We just need it in the software repo so we can then query the Github API.

[KTS915]

Now all tackled in the mu-plugins -> software-submit-form.php file.

For plugins, we get the description from the README.md file, but fall back on the readme.txt description (and then header in the readme.txt file if necessary). We get the headers from the main .php file, but again use the readme.txt file as a fallback.

For snippets, we again get the description from the README.md file. There's no need for a fallback here, since there's no WP equivalent. We get the headers from the main .php file, and again without a fallback.

For themes, we get the description from the README.md file, but fall back on the readme.txt description (and then header in the readme.txt file if necessary). We get the headers from the style.css file, but again use the readme.txt file as a fallback.

In all cases, we're now requiring the minimum CP version (styled in the header as "Requires CP") to be listed with the other headers and we're not providing an option for it to be entered manually into a form (which is unnecessary, could cause unintentional confusion, and is open to abuse).

The main issue this leaves is how much should get updated by a daily cronjob from the Directory to the repo. I have opened Issue #23 to track this.