The Plugins directory and readme.txt files

Every once in a while, somebody pings me to say that their plugin isn’t showing up properly in the directory. Almost always it’s a problem with the plugin itself having incorrect information somehow. So I thought I’d do a quick post to explain some aspects of the plugin directory, and explain some of the more obvious stuff which a lot of people miss.

Layout

First, let’s briefly go over the layout of your plugin in the SVN repository. There’s three directories created by default, and an optional fourth one that you can create yourself.

Trunk: The /trunk directory is where your plugin code should live. The trunk can be considered to be the latest and greatest code. It’s the development version. Hopefully, the code in trunk should always be working code, but it may be buggy from time to time because it’s not necessarily the “stable” version. For simple plugins, the trunk may be the only version of the code that exists, and that’s fine as well.

Tags: The /tags directory is where you can put versions of the plugin at some specific point in time. Usually, you’ll use version numbers for the subdirectories here. So version 1.0 of the plugin would be in /tags/1.0, version 1.1 would be in /tags/1.1, and so forth. Again, not every plugin uses tags for versioning.

Branches: The /branches directory is a place that you can use to store branches of the plugin. Perhaps versions that are in development, or test code, etc. The WordPress.org system does not use the branches directory for anything at all, it’s considered to be strictly for developers to use as they need it.

Assets: The last optional directory doesn’t exist by default (Edit: It does now, older plugins may be missing it, but all newly added plugins will get it by default.) You can create it yourself though. Just make a directory called “assets” next to those other three directories. Assets currently only has one use, which is to store the banner image to be displayed on your plugin page. We may use it for more things in the future. For now, you can just make an image, name it banner-772x250.png or banner-772x250.jpg, and put it in there. Easy.

Additional Info: Since creating this post, some new files have been added to the assets folder. You can create a banner-1544x500.png or banner-1544x500.jpg now too. This high-resolution banner will be shown to users with high-resolution displays, such as phones or tablets or certain newer laptops. Additionally, screenshots which once lived in the plugin’s own directory can now be moved from there into the assets directory. This allows the screenshots to be shown on the plugin page, but not included in the download of the plugin, reducing file size. It’s recommended to put screenshot files in /assets.

Parsing the plugin information

All plugins contain a main PHP file, and almost all plugins have a readme.txt file as well. The readme.txt file is intended to be written using a subset of markdown.  The example readme.txt explains most everything pretty well, but there’s a few little tidbits that are worth pointing out.

First is the concept of the “Stable Tag”. When WordPress.org parses the readme.txt, the very first thing it does is to look at the readme.txt in the /trunk directory, and then read that “Stable Tag” line. If the Stable Tag is missing, or is set to “trunk”, then the version of the plugin in /trunk is considered to be the stable version. If the Stable Tag is set to anything else, then it will go and look in /tags/ for the referenced version. So a Stable Tag of “1.2.3″ will make it look for /tags/1.2.3/.

Important bit: Everything else is read from this new location. If the Stable Tag is 1.2.3 and /tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in /trunk/readme.txt, and Stable Tag isn’t trunk, then your changes won’t do anything on your plugin page. Everything comes from the readme.txt in the file being pointed to by the Stable Tag.

Now let’s get to the plugin information itself. The WordPress.org directory reads the main plugin PHP file to get things like the Name of the plugin, the Plugin URI, and most importantly, the version number. On the plugin page, you’ll see the download button which reads “Download Version 1.2.3″ or similar. That version number comes from the plugin’s main PHP file.

Some people get this versoning confused due to the tags system. The Stable Tag points to a subdirectory in the /tags directory. But the version of the plugin is not actually that, it’s the version that is listed in the plugin’s PHP file itself. If you have changed Stable Tag to 1.4 and the plugin still says 1.3 in the PHP file, then the version listed will be 1.3.

Readme.txt pieces that everybody gets wrong

Back to the readme.txt. There’s a line called “Contributors”. This line has always been expected to be WordPress.org usernames only. WordPress reads those, gets information about that user, gets their gravatar, name, etc, and makes the authors listing. If you put anything here that’s not a WordPress.org username, then it doesn’t look nearly as good. No picture, no link, just text.

Other information in the readme.txt is read and used at various points on the Plugin listing. The Donate link makes a “Donate to this plugin” link in the sidebar. The “Requires at least” and “Tested up to” fields are used for compatibility checking, even on the WordPress installation itself. Few people get these wrong.

One thing a lot of people get wrong is this line:
“Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.”

That bit is serious, and you should read it again. That one line people get wrong more often than anything else. That line of text is the single line description of the plugin which shows up in big letters right under the plugin name, and if it’s longer than 150 characters, it gets cutoff and makes your plugin page look silly.

Markdown allows for easy linking in your readme.txt as well. Just write like this to link a word to a URL:

[WordPress](http://wordpress.org)

Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode. More on that topic here: http://wpdevel.wordpress.com/2010/02/20/plugins-can-now-include-videos-in-their-readme-txt-files/

Summary

I don’t think I covered everything, but hopefully that will explain some of the more obscure features of the directory and how it works. If it reduces the number of times people send me the question “why didn’t my version change show up in the directory”, then I think this post was time well spent. :)