Posted on

Listing WordPress Plugins

Cyber Sprocket has finally crossed the threshold into the world of full time WordPress Plugin Developer.   Over the past few months we  reached the point where we can now assign a full time employee to help support and update our small collection of WordPress plugins.    In the 2 years it has taken to get to this point we have learned a lot of things about how to list a plugin.

Today, I came across a blog post on the WordPress developer site that touches on a lot of things we learned the hard way… by good old-fashioned trial-and-error.   Here are the excerpts of things we found most useful.

Repository Layout

We use git as our local version control system.   When we are ready to go to production (aka “release to manufacturing” / RTM) we have a script that populates our local WordPress svn repository so we can push to the production server at WordPress.    As we have found there are a number of things that can go wrong if your repository is not setup properly.

One of the most damaging things is to have a second copy of trunk within one of the tags or branches of the svn repository.   If you do this you will almost always give your users a  downloadable plugin that will immediately break their website when activated with an “headers already sent” or “unknown header” error

Luckily the fix is easy, find the second copy of the trunk code, usually living in a sub-directory under a tag or branch directory, delete it (with svn del) and re-push the repo.

Here are other layout hints from the article (edited for space):

SVN repository layout for plugins, these are the directories you need:

Trunk: The /trunk directory is where your plugin code should live. The trunk can be considered to be the latest and greatest code. 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.

Branches: The /branches directory is for test code. The WordPress.org system does not use the branches directory. It’s considered to be strictly for developers to use as they need it.

Assets: The last optional directory doesn’t exist by default. Assets currently only has one use, which is to store the banner image to be displayed on your plugin page.

 

Readme.Txt

If you are creating a plugin, please take the time to fill out the readme.txt and make it more than a few brief lines saying something like “this is a plugin”.  Yeah, we got that.   Add a real description, some tags, SOME SCREEN SHOTS, and other information.  Look around at the plugin directory and find those that have more than a few sentences here.    The less information in the readme file the less likely it is that the developer has spent time creating a truly useful and complete plugin.    Also, screen shots.  Did we mention that?  People shop with their eyes.   I personally am 90% less likely to even consider a plugin without screen shots.  I want to see what the admin and user interfaces look like BEFORE I install it!

Here are some hints from the article about the readme.txt, again edited for space:

“Contributors”. This line has always been expected to be WordPress.org usernames only. 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.

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.

The description 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. 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/

 

If you have helpful hints or tips on publishing WordPress plugins please share.