Plugin readme.txt 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.