Plugin Readme File draft

Projects Directory
1

Draft of the Plugin Readme File document is below. I’m not sure if there are any other allowed sections?

Plugin Header Requirements

To appear correctly in the ClassicPress Plugin Directory, each plugin should have a readme.txt or README.md file which includes certain required information and can also contain some additional optional information.

The readme header information contains the required information (there is an overlap with the content of the plugin header):

  • Contributors - A case sensitive, comma separated list of all ClassicPress Forum usernames who have contributed to the code. Some contributors may ask to be removed from the list and it is recommended to honor this request.
  • Tags - A comma separated list of between 1 and 12 terms which describe the plugin. Plugins must not use competing plugin names as tags.
  • Donate link - A "Donate to this plugin" link will be displayed on the sidebar of the plugin settings page. If this is not supplied, the donate sidebar will not be displayed.
  • Requires - The lowest version of ClassicPress with which the plugin is compatible (e.g. 1.0. or 1.4); note that only the major and minor numbers need to be specified as the patch version should not cause a plugin to break.
  • Tested - The version of ClassicPress with which the plugin has been tested (e.g. 1.0. or 1.4); note that only the major and minor numbers need to be specified as the patch version should not cause a plugin to break.
  • Requires PHP - The lowest version of PHP with which the plugin is compatible (e.g. 7.0 or 7.2).
  • License - The short name of the applied license, such as "GPLv2 or later". All plugins submitted to the ClassicPress Plugin Directory must be licensed under a GPL license or have a GPL compatible license.
  • License URI - A link to the full text of the license, such as http://www.gnu.org/licenses/gpl-2.0.html.

The final element of the readme header information is a short description, no more than 140 characters, of the plugin; this description must not use markdown or contain line breaks.

The readme file can contain several sections to provide additional information to users when they view the plugin details in the ClassicPress Admin; these sections can use a modified version of Markdown.

Instructional videos, hosted on sites such as YouTube or Vimeo, can be included within these sections simply by placing the video link on a line by itself.

The additional sections which can be included are:

  • Description - A longer description of the plugin which can include detailed instructions on how to use the plugin. Unlike the short description, this description section can include both line breaks and markdown.
  • Installation - This section is only needed if there are custom configuration steps which need to be followed post-install.
  • Frequently Asked Questions - This section is only needed if you want to include additional information in the form of an FAQ section.
  • Screenshots - Screenshots can be added to the /assets/ folder of a plugin named like screenshot-1.png where accepted file types are png, jpg, jpeg and gif. When adding them to the readme file, add them using a numeric list.
  • Changelog - This section must be included so users can see what has changed between versions of the plugin. The change log should be ordered with the newest version at the top and oldest at the bottom.
  • Upgrade Notice - Explains the reason why the user should upgrade and must be no more than 300 characters per notice.
  • Other Notes - This section can be used if you have information to include which does not fit into one of the other sections.

This is an example of how a readme file might look:

=== My Plugin ===
Plugin URI: https://www.example.com/plugins/my-plugin/
Contributors: JohnSmith
Tags: term1, term2
Donate link: https://www.example.com/donate/
Requires: 1.4
Tested: 1.4
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

This is a short description of the plugin, no lore than 150 characters in length and with no markdown or line breaks.

==Description ==

This is the long description of the plugin and is not limited as to length and can also include line breaks and, like all other sections described below, make use of markdown to make the section more readable.

== Frequently Asked Questions ==

= The first question =
The answer to the first question.

= The second question =
The answer to the second question.

== Screenshots ==

1. Screenshot 1 showing the first settings page.
2. Screenshot 2 showing the second settings page.
3. Screenshot 3 showing the plugin output on the front end.

== Changelog ==

= 2.0.0 =
* A breaking change.

= 1.1.0 =
* A new feature.
* A bug fix.

= 1.0.1 =
* A bug fix.
* A second bug fix.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 2.0 =
Upgrade to get access to major new functionality.

= 1.0.1 =
Upgrade immediately: this version fixes a security bug.

== Other Notes ==
Some other notes which provide more information in the plugin details in the ClassicPress Admin.
1 Like
2

There are a couple of typos: whch plguni ClssicPress whuch ;imited (maybe more)
Are we using US English or other English: honour vs. honor

Why use forum user names? It seems like GitHub names might be better. Are the user names going to be linked?

12 tags seems like a lot. WP limits tags, and then only uses the first 5 and only shows a tag if it has more than one usage.

I suggested over at WP to use a range for the versions, but no one wanted that. The intent was to automate, using Tide (which is still going). As seen in a recent forum question about migration, the upper version of a range can be a limiting factor (PHP 8).

Does HTML work in the description? The example should be formatted a little better to make the point.

Would the assets folder holding screenshots be a part of the plugin’s zip file?

Changelog should recommend that the most recent is at the top.

I suggest that the format of this file be the same for plugins and themes.

3

I have spent considerable amount of time researching readme and what is possible therein/ these are the optimal results I came up with better-wp-plugin-boilerplate/plugin-name/README.txt at 6b6928701129411fec599f8df659ca71cf0a6051 · TukuToi/better-wp-plugin-boilerplate · GitHub

Main difference to the common one is the php code block.

Maybe it helps :slight_smile:

I also started using changelog.txt file instead of the readme, which may or may not be correct but :works:

1 Like
4

It seems on one computer Notepad++ does spellcheck and on the other it doesn’t. Odd as I’m not aware of changing a setting for that. I’ve gone through and corrected typos; I’m generally trying for US English, but the correct spelling is too strong a habit to entirely break.

@wadestriebel would names be form names for directory or GitHub names? I’d think the former?

12 tags is what the WP docs say so I went with it. This depends on how we handle it in the directory and I don’t think a decision for that has been made yet?

Does markdown handle HTML as this would be displayed in the plugin details window?

I rarely do screenshots; can someone confirm where do these live in a plugin?

As I’ve mentioned before, once the plugin version is complete, I’ll adapt where necessary for themes, but I think that they largely should be the same for both plugins and themes.

1 Like
5

I would recommend forum names, as we will open support for other git providers in the future and there is a chance of collision across there.

12 seems like a lot, but I guess we can always tweak it. I think what we will likely do in search is favour the first tags higher than the last tags.

It does :+1:

6

Screenshots are added to a separate folder not within the plugin called assets
See assets in tkt-maintenance – WordPress Plugin Repository as example

7

Ok, so that sort of assets folder wouldn’t work as there wouldn’t be one.

The WP fallback appears to be the old way of in the root of the plugin folder.

8

Wherever this is published, there should be a link to a validator. If it has a preview, even better.
Someone was asking at WP meta today where the code is so they can contribute. The WP readme parser is at:
https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/readme/class-parser.php
There is one with a preview at https://wpreadme.com/

Or is the CP directory leveraging GitHub for showing the readme? (an iframe?)

Edit: looking at the code from WP meta, I see your list left out “Upgrade Notice”.

9

You supplied the link a while ago (thanks for posting it); I started forking it so we could remove the bits we didn’t care about.

I recently thought we could also include a plugin header checker in it too.

I need to gte it finished off.

10

I wasn’t aware of upgrade notices, but have updated to include.

Thanks for pointing it out.