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. 
Marcus 7:32 am on June 10, 2012 Permalink |
I must admit, I’ve made one or two of these mistakes starting off
Useful article, it would go great linked somewhere in the developer center, as I’m sure that’s where people starting would look first.
Lance Cleveland 2:37 pm on July 12, 2012 Permalink |
Don’t forget about the new “high definition” banners for the header image. If memory serves this is twice the resolution of the standard banner in the assets directory at 1444×500.
Otto 2:39 pm on July 12, 2012 Permalink |
It’s 1544×500, and I created that post (and code) after I wrote this post.
http://make.wordpress.org/core/2012/07/04/fun-with-high-dpi-displays/
Lance Cleveland 4:02 pm on July 12, 2012 Permalink |
I figured that is what happened, just thought it would be good to have a “note” (comment) so future readers would know it existed. Thanks for the clarification as well. I couldn’t find the original notification about the resolution. I thought 1444 looked odd.
Mike Schinkel 7:16 pm on August 3, 2012 Permalink |
Just replying so I can get subscribed to this blog (might be another way, but can’t figure out how.)
Otto 7:40 pm on August 3, 2012 Permalink |
Good point. I added the subscription widget to the sidebar.
Brad Touesnard 3:53 pm on August 17, 2012 Permalink |
@Otto Would it be possible to start supporting the filename README.md in addition to readme.txt? A lot of developers host their plugins on GitHub as well but the filename readme.txt isn’t run through the markdown parser at GitHub. It would be nice if .org supported the README.md filename as well.
Otto 4:12 pm on August 17, 2012 Permalink |
The flavor of markdown we support isn’t the same as theirs (ours is very limited), so you’d need to have separate files anyway. So, using a separate readme.txt file makes more sense.
WorldofHacker 6:44 pm on February 4, 2013 Permalink |
Yes, adding README.md option is nice idea, +1.
if anyone here is unclear about the extension .md , here is the link for them => http://www.fileinfo.com/extension/md
WORDPRESS PLUGINS DEVELOPMENT | WordPress Family 5:22 pm on August 26, 2012 Permalink |
[...] For other problems check Otto’s good write-up of common problems: The Plugins directory and readme.txt files [...]
Segnalibri al 29 settembre 2012 | aldolat 7:07 pm on September 30, 2012 Permalink |
[...] The Plugins directory and readme.txt files [...]
Gwyneth Llewelyn 10:12 pm on November 18, 2012 Permalink |
Ok, I’m a bit confused now.
“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.”
So if I understand this correctly, the best way to deal with this scheme is simply to have a single file under /trunk/, which is readme.txt, and that needs only to hold 9-10 lines or so with the headers — and just point to the “Stable Tag”? Then the *rest* of the readme.txt *which is under the tag, not trunk* will be read & parsed instead? I don’t need to have a full copy of readme.txt both under /trunk/ *and* /tags/X.Y.Z/ ?
You see, I hate unnecessary file duplication
I love the idea of having a super-small, 9-line only, readme.txt file under /trunk/ which just points to the correct place. Also, it makes this far easier to revert to earlier versions in case something goes seriously wrong!
Sorry if all of this sounds incredible obvious to you seasoned plugin developers
Gwyneth Llewelyn 10:44 pm on November 18, 2012 Permalink |
Maybe all that’s needed on trunk/readme.txt is 2 lines after all:
=== Plugin Name ===
Stable tag: X.Y.Z
Is that right? The remaining readme.txt will come from tags/X.Y.Z instead? If so, this is just awesome!
Gwyneth Llewelyn 1:20 am on November 19, 2012 Permalink |
Seems to work exactly as I thought
Samuel Wood (Otto) 4:38 am on November 19, 2012 Permalink |
Yes, that works.
No, you absolutely should not do it that way.
There is a *convention* in place here. People expect trunk to contain the latest development code of your plugin. In other words, the latest and greatest code, unstable changes and all, belongs in trunk. The latest stable, versioned, tagged code, will be in a tags directory.
The directory is based around this concept. There are beta-tester plugins which assume this to be true. Forget about “duplicated files”, do it the way everybody else does it so that you don’t mess up the friggin’ system.
Put your development code in trunk. Tag the ready-for-release versions of the code in the tags directory. This is the best way to manage things. Even repository systems such as git and github have the concept of a main trunk for development and tags for versioning. The goal isn’t to make things easier for you to manage, the goal is to make the code accessible to everybody else in a sane way.
Gwyneth Llewelyn 4:42 pm on November 19, 2012 Permalink |
Thanks for the clarification and I do apologise if I have understood you wrongly. Maybe you should clarify that duplication of everything continues to be mandatory, and not optional, to stick to conventions. Your article, read in a certain light, seemed to convey the idea that the convention was changed exactly for the benefit of keeping things simple.
I’m not here to discuss what is better and what is not — I’ve just asked the question on how to do things from now on because the article lead to believe me that the convention had changed, or, if it hadn’t, that “beginners were always making mistakes and can do things in much simpler ways if they understand the directory structure better”. And I appreciate your answer: no, nothing has changed.
“The goal isn’t to make things easier for you to manage”. Why not? KISS is always a good philosophy, IMHO.
Samuel Wood (Otto) 4:59 pm on November 19, 2012 Permalink |
It’s not really duplication though. SVN doesn’t store files that way, it really just stores changesets. The trunk/tags/branches convention is SVN’s, not ours. You can tag things using an svn copy operation, and that’s not making new files in svn, just marking copies of the files at a specific point in time.
The Stable Tag and readme.txt stuff is indeed ours, simply for the purpose of keeping things in the directory sane.
brasofilo 2:08 pm on December 18, 2012 Permalink |
Finally I got the /tags/ concept and am correcting a wrongful use of the “Stable Tag” (I had it declared, but the version was not present in the tags folder), although the system was kind enough to make it work.
Now, I’m looking for articles on how to use the /trunk/ when developing a new version of the plugin.
I mean, is it possible to install and update from there?
Samuel Wood (Otto) 5:56 pm on December 18, 2012 Permalink |
Trunk should be the “beta” version, and have its version numbers indicating such. So if my Stable Tag was like 1.0, and I had a /tags/1.0 directory, then I could make trunk’s version into 1.1-beta or something like that, and make all the changes I liked, then when it was ready for release, change it to 1.1 and tag it and update the Stable Tag field in the readme.txt to point to the new one.
If you use this sort of structure, with trunk containing the latest beta code, then you can easily use a plugin like http://wordpress.org/extend/plugins/plugin-beta-tester/ to update to that beta version on a site.
brasofilo 7:29 pm on December 18, 2012 Permalink |
Perfecto, Otto, gracias!
Kreative Charge | Creating a WordPress Plugin 11:59 am on December 30, 2012 Permalink |
[...] For other problems check Otto’s good write-up of common problems: The Plugins directory and readme.txt files [...]