Add a WordPress Plugin to the Directory using Subversion on Windows

0

Two of my plugins – the WordPress Comment Rating Field Plugin and the WordPress Insert Link Class Plugin – are published on the wordpress.org Plugin Directory.

Having never done this before, I created the following guide for publishing your first plugin to the WordPress Plugin Directory, as well as how to provide versioned updates.

Creating a New Plugin

  1. Visit the WordPress Plugin Directory, and login at the top of the screen (if you don’t already have a free wordpress.org account, you’ll need to create one).
  2. Visit the Add New Plugin page, and enter a suitable plugin name and brief description about the plugin.  For the URL, this should point to your web site where the plugin details can be found / will be found.
  3. Whilst your repository is being created (this can take between 15 – 30 minutes), download and Install TortoiseSVN
  4. On your computer, create a new, empty folder for your plugin.  I always use the plugin programmatic name here.  Using the WordPress Comment Rating Field Plugin as an example, I created a folder called comment-rating-field-plugin
  5. Right click on the newly created folder, and select SVN Checkout
  6. Enter the URL of your plugin repository.  You will have received this via email, and typically it follows the plugin name (in my example, its http://plugins.svn.wordpress.org/comment-rating-field-plugin).  Click OK
  7. You’ll be prompted for a username and password – this is the same username and password as used in step (1)
  8. You should now see new subfolders; double click to go into the trunk folder.
  9. Place your plugin files within this folder (i.e. comment-rating-field-plugin.php and associated files), and work on them as necessary.

At this point you have the necessary file and folder structure.  However, you’ll also need to ensure that:

  • The plugin has the correct PHP docblock comment formatting.  For example:
1
2
3
4
5
6
7

/**
* Plugin Name: Comment Rating Field Plugin
* Plugin URI: http://www.n7studios.co.uk/2010/06/04/wordpress-comment-rating-field-plugin/
* Version: 1.02
* Author: <a href="http://www.n7studios.co.uk/">Tim Carr</a>
* Description: Adds a 5 star rating field to the comments form in Wordpress.  Requires Wordpress 3.0+
*/
  • Inside the trunk folder, you need a readme.txt file, as well as any screenshots to show the plugin functionality.  Each screenshot should be named screenshot-X.jpg, where X is a sequential number starting from 1, based on the number of screenshots you have.
  • The readme.txt file should follow a specific format.  For example:
=== Comment Rating Field Plugin ===
Contributors: Tim Carr
Donate link: http://www.n7studios.co.uk/2010/06/04/wordpress-comment-rating-field-plugin/
Tags: comment,rating,field
Requires at least: 3.0
Tested up to: 3.1.3
Stable tag: trunk

Adds a 5 star rating field to the end of a comment form in WordPress, allowing the site visitor to optionally submit a
rating along with their comment. Ratings are displayed as stars below the comment text.

== Description ==

Comment Rating Field Plugin is a plugin which adds a 5 star rating field to the end of a comment form in WordPress,
allowing the site visitor to optionally submit a rating along with their comment. Ratings are displayed as stars below
the comment text.

== Installation ==

1. Download the Comment Rating Field Plugin.
2. In your WordPress Administration, go to Plugins > Add New > Upload, and select the plugin ZIP file.
3. Activate the plugin
4. Ensure that your comments.php theme file has its form id set to commentform.

== Frequently Asked Questions ==

== Screenshots ==

1. Comment Rating Field Plugin on Comment Form
2. Star rating displayed below comment text 

== Changelog ==

= 1.02 =
* Change to readme.txt file for required ID on comment form.

= 1.01 =
* Fixed paths for CSS and Javascript.

= 1.0 =
* First release.

== Upgrade Notice ==

Finally, you’ll need to validate your readme.txt file, which can be done at http://wordpress.org/extend/plugins/about/validator/

Publishing your New Plugin

  1. Once you are ready to publish your plugin to the WordPress Directory, right click on the trunk folder and select SVN Commit
  2. You will be asked to enter a message; I would enter something descriptive, so you can look back at your history and understand what this action was for.  In our example, I would write Adding Comment Rating Field Plugin Version 1.0
  3. Ensure that the select / deselect all option is ticked, and click OK
  4. You may be again prompted for your WordPress.org username and password.
  5. Right click on the trunk folder again, and select TortoiseSVN > Branch / Tag
  6. For the To URL field, ensure it has your plugin SVN URL, with /tags/1.0 added to the end.  For example, http://plugins.svn.wordpress.org/comment-rating-field-plugin/tags/1.0
  7. Check the box for HEAD revision.
  8. Message = Tagging Version 1.0
  9. Click OK

Your plugin is now published, and after a short delay should appear on the plugin page on WordPress.

Feedback

Users who install and try out your plugin may have feedback or issues.  They will typically raise these via:

  • The WordPress Support Forums.  To find posts specific to your plugin, visit your profile on wordpress.org > plugin name > admin > Support Forums Tag (or use the URL format http://wordpress.org/tags/comment-rating-field-plugin, where comment-rating-field-plugin is your plugin programmatic name).
  • Your web site, depending on the URL specified in the plugin’s docblock comment file.

It’s useful to keep track of these two main sources as they’ll not only provide issues on potential bugs, but also feature requests, which if repeated by several users may be beneficial to add to your next version.

Updating your Existing Plugin

If you decide to add new functionality or fix some bugs in your plugin:

  1. Work on the trunk folder again, making changes as necessary.
  2. Remember to update the version number in the PHP docblock comment
  3. Remember to update the readme.txt file, specifically:
    Requires at least
    Tested up to
    ChangeLog
  4. Right click the trunk folder, and click SVN Commit
  5. Message = Adding PluginName Version x.x (where PluginName is the name of your plugin, and x.x is the new version number you’ve assigned.  As a rule of thumb, if you’re making a minor edit, increment by minor version e.g. 1.1; if you’re making a major overhaul, increment the major version e.g. 2.0)
  6. Show unversioned files = ticked
  7. Select / deselect all = ticked
  8. Click OK

This updates the trunk, which is the main plugin, with the WordPress Repository.  The new version will then be available within 15 – 30 minutes for download, and existing users who already have the plugin installed will see an update notice in their WordPress Plugin Administration Panel.

As with the creation of a new plugin, we also need to tag this version.  This is useful in case you need to roll back to an older version of your code (for example, if a newer version introduces a major bug and, as a quick fix, you require the older codebase to use as the main plugin trunk instead).

  1. Right click /trunk folder
  2. TortoiseSVN > Branch / Tag
  3. To URL = tags/x.x (where x.x is the new version number)
  4. HEAD revision in the repository = selected
  5. Message = Tagging Version x.x (where x.x is the new version number)
  6. Click OK

 

 

Leave a Reply

Your email address will not be published. Required fields are marked *

*