[wp-hackers] readme.txt spec

[Mark Jaquith]

On Oct 24, 2006, at 5:25 PM, Mark Jaquith wrote:

> The readme.txt spec for plugins hosted on wp-plugins.org is getting  
> some fresh air blown into its lungs

I've been working with Michael Adams on fleshing out the readme.txt  
format, and have built a parser/validator/dingus for the currently  
proposed version.

You can access the readme parser here:
http://covered.be/readme-validator/

It accepts copy-paste or a readme.txt URL

Some of the changes:

- "Minimum version" and "tested with" have been renamed to improve  
natural language flow and clarification (i.e. "tested with") implies  
that's the only version that's been tested.

New versions:

Requires at least: 2.0
Tested up to: 2.1

- We're moving the full description into its own section, and having  
the old description area act as a markup-less 150 char summary.  If  
the new == Description == section doesn't exist, the old one will be  
used as a fallback (which makes this new format backwards compatible  
with the originally proposed format)

- "Stable tag" can refer to either a Subversion tag, or "trunk" (if  
you put your stable version in trunk).  Obviously, the readme.txt for  
your in-development version should be changing as your plugin  
matures, so if you point to a stable tag, it is that readme.txt  
that'll be used as the defining one for your plugin.  That allows you  
to develop in trunk, updating the /trunk/readme.txt to document new  
features, without disturbing the readme.txt of your designated stable  
tag.

Here is an ideal readme.txt, according to the proposed format that  
Mike and I came up with.  Let me know if you find any shortcomings in  
the parser, or if you have any clarification questions.






=== Plugin Name ===
Contributors: markjaquith, mdawaffe
Tags: comments, spam
Requires at least: 2.0.2
Tested up to: 2.1
Stable tag: 4.3

Here is a short description of the plugin.  This should be no more  
than 150 chars.  No markup here.

== Description ==

This is the long description.  No limit, and you can use Markdown (as  
well as in the following sections).

For backwards compatibility, if this section is missing, the full  
length of the short description will be used, and Markdown parsed.

A few notes about the sections above:

* "Contributors" is a comma separated list of wp.org/wp-plugins.org  
usernames
* "Tags" is a comma separated list of tags that apply to the plugin
* "Requires at least" is the lowest version that the plugin will work on
* "Tested up to" is the highest version that you've *successfully  
used to test the plugin.*  Note that it might work on higher  
versions... this is just the highest one you've verified.
* Stable tag should indicate the Subversion "tag" of the latest  
stable version, or "trunk," if you use `/trunk/` for stable.  Note  
that the `readme.txt` of the stable tag is the one that is considered  
the defining one for the plugin, so if the `/trunk/readme.txt` file  
says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt`  
that'll be used for displaying information about the plugin.  In this  
situation, the only thing considered from the trunk `readme.txt` is  
the stable tag pointer.  Thus, if you develop in trunk, you can  
update the trunk `readme.txt` to reflect changes in your in- 
development version, without having that information incorrectly  
disclosed about the current stable version that lacks those changes  
-- as long as the trunk's `readme.txt` points to the correct stable  
tag.  If no stable tag is provided, it is assumed that trunk is  
stable, but you should specify "trunk" if that's where you put the  
stable version, in order to eliminate any doubt.

Ordered list:

1. Some feature
1. Another feature
1. Something else about the plugin

Unordered list:

* something
* something else
* third thing

`<?php code(); // goes in backticks ?>`

== Installation ==

This section describes how to install the plugin and get it working.

e.g.

1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory
1. Activate the plugin through the 'Plugins' menu in WordPress
1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates

== Frequently Asked Questions ==

= A question that someone might have =

An answer to that question.

= What about foo bar? =

Answer to foo bar dilemma.

== Screenshots ==

1. This screen shot description corresponds to screenshot-1.(png|jpg| 
jpeg|gif)  Note that the screenshot is taken from the directory of  
the stable readme.txt, so in this case, `/tags/4.3/screenshot-1.png`  
(or jpg, jpeg, gif)
2. This is the second screen shot

== Arbitrary section ==

You may provide arbitrary sections, in the same format as the ones  
above.  This may be of use for extremely complicated plugins where  
more information needs to be conveyed that doesn't fit into the  
categories of "description" or "installation."  Arbitrary sections  
will be shown below the built-in sections outlined above.