Getting your plugins listed in the official WordPress Plugin Directory is considered a chore by many, but it’s nothing that should stop you from sharing your plugin with the community at large. Up until now, I haven’t really bothered with adding my plugin collection to the Directory, but after Herb Goodman helped to package my recent Block Bad Queries plugin, I figured now was a good time to dig in and learn the ropes. It turns out the process only took about an hour to complete, not including the waiting period for access to the Subversion Repository (which was about 18 hours). Definitely worth the potential exposure provided by having your plugin listed in the official directory.

If you are a seasoned plugin developer, you already know how to hook it up at the WordPress Directory, but for those who don’t, this DiW tutorial will show you everything you need to know.

Why host your plugin at the WP Directory?

Some of the benefits of hosting your plugin at the WordPress Plugin Directory:

• Track basic statistics regarding how many people are downloading and when
• Provide a centralized location for users to leave comments and feedback
• Get your plugin rated against the many other hosted WordPress plugins
• And of course, give your plugin greater exposure to the WP community

Further, it seems that plugins hosted at the official directory are perceived to be associated with a greater degree of “trustworthiness.” People trust WordPress, and they also trust the various resources (plugins, themes, etc.) made available to them through the wordpress.org website. Basically, if you’re writing plugins for the WordPress community, you should be sharing them with as many people possible. The Plugin Directory does this exceedingly well.

“Worth playing for?” Let’s look at a quick overview before digging into the specifics of getting your plugin added to the Directory..

Overview

To help get a sense of direction before getting started, consider this overview of events:

• Write and prepare your plugin
• Prepare the readme.txt file
• Sign up for access to the Subversion Repository
• Wait for approval and SVN access information
• Use Subversion software to upload your plugin files
• Wait a few minutes for the system to add your plugin to the Plugin Directory

Of course, the big hurdle that many “would-be” contributors have is using the SVN/Subversion system and software. To be honest, this was one of the reasons why I never bothered adding my other plugins, but now that I’ve seen how easy it actually is (once you learn it), I will most likely add my other plugins as well (eventually).

First steps

First, get your plugin and files ready. You don’t need to compress anything with zip or tar because the SVN system will do that automatically for you based on the contents of your plugin. In my case, the plugin was Block Bad Queries, which contains the following two files:

• block-bad-queries.php
• readme.txt

The actual plugin file is the “block-bad-queries.php”. The “readme.txt is the only other required file. If you have multiple plugin files, that’s fine too, they will be uploaded and managed together during the subversion process.

For more information on getting things ready, check out Plugin Submission and Promotion at the Codex. A key factor in the process is a well-written readme.txt file, which we’ll look at next..

Pimp your readme.txt file

I think having a well-prepared readme.txt file is one of the things that helped everything go smoothly for my first time out. Your plugin’s readme.txt is used for the content of the various pages in a typical plugin listing:

• Plugin Name
• Description
• Installation
• Faq
• Screenshots
• Other Notes
• Changelog
• Stats
• Admin

That’s basically it. If your readme.txt contains each of these sections, you should be good to go. There are various details required for certain sections, such as the opening “Plugin Name” information, which requires the following specifics (using BBQ as an example):

=== Plugin Name ===

Contributors: Jeff Starr
Plugin Name: Block Bad Queries
Plugin URI: http://perishablepress.com/press/2009/12/22/protect-wordpress-against-malicious-url-requests/
Tags: wp, protect, php, eval, malicious, url
Author URI: http://perishablepress.com/
Author: Perishable Press
Requires at least: 2.3
Tested up to: 2.9
Stable tag: 1.0
Version: 1.0 

I think we’re all familiar with this type of information – something similar is included at the top of virtually every plugin (and theme) in existence. In any case, this is the first part of a proper readme.txt file, as seen in the WordPress/bbPress plugin readme file standard, which also contains details and further information about the various requirements.

So, to put all of this together and create your own readme.txt file, just copy & paste the following template into a blank .txt file and flesh it out with your own details:

=== Plugin Name ===

Contributors:      (plugin contributors)
Plugin Name:       (name of your plugin)
Plugin URI:        (web page for plugin)
Tags:              (tags for the plugin)
Author URI:        (plugin authors site)
Author:            (the plugin's author)
Donate link:       (a link for donating)
Requires at least: (minimum required WP)
Tested up to:      (tested WP up to ver)
Stable tag:        (plugin's stable ver)
Version:           (plugins current ver)

== Description ==

== Installation ==

== Upgrade Notice ==

== Screenshots ==

== Changelog ==

== Frequently Asked Questions ==

== Donations ==

Aside from wanting to put the “Plugin Name” section at the top of the file, these different sections can be rearranged in any order, but they all need to be present in order to adhere to WordPress guidelines and pass the readme validation. For more information on fleshing out each of these different sections, check out the standard readme.txt example. Once you get everything pimped and ready, the readme validator will display the good news:

Your readme.txt rocks. Seriously. Flying colors.

If you don’t see this message, you’ll get a list of things that need fixed in order to pass validation. The validator is a great tool that makes it easy to put together a proper readme.txt file.

A few notes on the readme file

Here are a few notes that I found helpful while creating the readme.txt file:

• The readme file uses markdown for marking up your info with links, lists and so on.
• You may use PHP in your readme content (escape with backticks: `<?php ?>`)
• Use asterisks for *emphasized text*
• Use double asterisks for **strong text**

As you can see, the readme.txt file is quite flexible, enabling you to customize your plugin’s information as provided in the Plugin Repository.

Prepare the plugin file

After creating and testing your plugin, you need to give it a license. Here is what the WordPress Codex has to say about it:

• Your plugin must be GPLv2 Compatible.
• The plugin most not do anything illegal, or be morally offensive.
• You have to actually use the subversion repository we give you in order for your plugin to show up on this site. The WordPress Plugins Directory is a hosting site, not a listing site.
• The plugin must not embed external links on the public site (like a “powered by” link) without explicitly asking the user’s permission.
• If you don’t specify a v2-compatible license, what you check in is explicitly GPLv2.

Once you’ve given your plugin the required license — either explicitly by including the license or implicitly by not including any license — you’re ready to get hosted at the Repository. Take a few deep breaths and clear your mind..

Sign up for access to the Plugin Repository

Now with your plugin files ready to go, visit the Sign-up page, login to your account, and fill out the form with the following information:

• Plugin Name (required)
• Plugin Description (required)
• Plugin URL

After submitting the form, be prepared to wait awhile to be approved access to the subversion repository. For my plugin, it took around 18 hours to receive a response. Just be patient, if everything looks good, someone will approve your request within a reasonably undefined amount of time. Eventually, you should receive an email with all the information you need to access the Subversion Repository. This is where you will upload and store your plugin. The system will use the files and information included in the Subversion Repository to generate the actual web pages that appear in the Plugin Directory with all of the other plugins. It usually takes a few minutes for the system to create your plugin’s entry, so be patient after uploading. Just as a general reference, I think I waited something like five or ten minutes before seeing my plugin listed in the Plugin Browser.

Use Subversion software to upload your plugin files

At this point, you’ve been granted access to the SVN repository and are ready to upload your files and call it done (until the next plugin update). To begin this task, familiarize yourself (if necessary) with the basics of using Subversion with WordPress. There’s a LOT to learn about Subversion, but don’t let that stop you from making quick use of it to get the job done.

What is Subversion?

Basically, Subversion is an open-source piece of software that people use to more easily manage files and directories as they change over time. The key thing about Subversion is that it enables you to restore previous versions of your data and understand how things have changed. This “time-machine” functionality is especially useful for managing things like continually changing source code, and makes managing thousands of plugins much easier.

How do I use Subversion?

To use Subversion, you’ll need some software. Mac people get it pre-installed with Leopard, and Windows peeps can download the binary installer here. Keep in mind that, for either operating system, Subversion is something you run through either Terminal (Mac) or the Command Prompt (Win) as a series of commands. As you can imagine, there are a gazillion commands available, but we’ll only be needing a select few for our purposes here.

Please don’t make me use the command line!

If the thought of using the command line to run software makes your stomach turn, you can use Subversion through a graphical interface such as Versions for Mac, and/or
Tortoise for Windows. I haven’t used either of these apps, but they certainly look more inviting than the command prompt, which is what we’re rolling with for this tutorial.

How does it work?

There are two sets of files we’re working with: local files (on your computer) and remote files (on the server). For each set of files, we want the following directory structure (using my plugin as an example):

root-folder/
	/trunk/
		block-bad-queries.php
		readme.txt
	/branches/
	/tags/

To get started, we’ll place our files into the /trunk/ directory, and then in the future add new versions to either the /branches/ directory (for major updates) or /tags/ directory (for minor updates).

Once uploaded, your files are stored in the central plugin repository on WordPress servers. From the repository, anyone can check out a copy of your file(s), but only you (the plugin author) have the authority to check in new file(s). Using Subversion, any changes made to your local files are mirrored exactly on the server, and eventually reflected in your plugin pages in the WordPress.org plugin directory.

Add your plugin to the Repository

Now that we have our files ready and Terminal (or Command Prompt) open, let’s wrap this up and upload our files to the Plugin Repository. Here’s an overview of what we’re going to do:

1. Check out the blank repository (i.e., the empty directory structure)
2. Add your files to the local /trunk/ directory on your computer
3. Update the repository with copies of your local files

Here’s how to do it with Mac Terminal, and it’s very similar for Windows Command Prompt:

$ mkdir my-local-dir
$ svn co http://svn.wp-plugins.org/your-plugin-name my-local-dir
$ cd my-local-dir/
my-local-dir/$ cp ~/my-plugin.php trunk/my-plugin.php
my-local-dir/$ cp ~/readme.txt trunk/readme.txt
my-local-dir/$ svn add trunk/*
my-local-dir/$ svn ci -m 'add some notes here'

And here are the same commands with comments and returned messages:

# create a local folder for your copy of the repository

$ mkdir my-local-dir

# download the empty directory structure to your new folder

$ svn co http://svn.wp-plugins.org/your-plugin-name my-local-dir
> A	my-local-dir/trunk
> A	my-local-dir/branches
> A	my-local-dir/tags
> Checked out revision 11325.

# copy your plugin files to the local trunk directory

$ cd my-local-dir/
my-local-dir/$ cp ~/my-plugin.php trunk/my-plugin.php
my-local-dir/$ cp ~/readme.txt trunk/readme.txt

# register the new files with Subversion

my-local-dir/$ svn add trunk/*
> A	trunk/my-plugin.php
> A	trunk/readme.txt

# update the Repository with the new files

my-local-dir/$ svn ci -m 'add some notes here'
> Adding	trunk/my-plugin.php
> Adding	trunk/readme.txt
> Transmitting file data ..
> Committed revision 11326.

# All done!

That may look like a mouthful, but it’s actually only about seven commands, even fewer if you manually create the directory structure and add the local files yourself. You should also keep the following notes in mind if you are new to the whole “command line” thing:

• Any line prefixed with a pound sign # is a comment and should not be used as a command.
• Lines beginning with a ”>” character indicate a response from the software and should not be used as a command.
• All of the specific file and directory names need to be changed to match your own.
• The “-m 'add some notes here'” in the last command is used to add notes for the event — they may be anything you wish (or none at all).
• At the last step, you may be prompted for your username and password, which should be the same as used when logged into the WordPress.org site.

After running those commands, your plugin will be in the Repository and ready for the system to automatically create your actual plugin pages as they will appear in the Plugin Directory. This usually takes some time, so grab a drink and kick back for around five to ten minutes. Eventually, you will see your plugin appear on the Newest Plugins page, and then also at its dedicated page, which will be something like this:

http://wordpress.org/extend/plugins/your-new-plugin/

Once you get this far, you’re golden. There are many other cool things you can do with Subversion to manage and update your plugin. To get started with updating and tagging, check out the How to Use Subversion in the Plugin Directory. And for even more information on the entire process of adding your plugins, check out the Plugin Developer FAQ.

Final thoughts..

Overall, getting my first plugin hosted at the WordPress Plugin Directory was a great learning experience that will make it easy to add other plugins in the future. Hopefully the fruits of my labor will help you when adding your own plugins to the Directory. As always, feel free to chime in with suggestions, questions and concerns about any of the techniques described here. It would be great to hear more about using Subversion (tips, tricks, etc.).

Also, if you are interested, you can see the result of all this work by checking out the Block Bad Queries (BBQ) Plugin at the Plugin Directory. There’s still a few details that need to be added/tweaked, but it’s great just having it in there.

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 7 comments | Add to
Delicious
Categorized: Plugins | Tagged: plugin, svn