Using Subversion with the WordPress Plugin Directory

Follow these step-by-step instructions to add and update plugins in the public WordPress Plugin Directory.

These essential steps from the video follow below:

• Getting Started with Your Plugin
• Register for a WordPress.org Account
• Request to Put Your New Plugin in the WordPress Plugin Directory
• Install an SVN Client For Your Machine
• Choose a Local Directory for Your Projects
• Your Plugin Request Approval Email
• Directory Terms for This Article
• Pulling the New Server Directory to Your Local Machine
• Finish Developing Your Plugin
• Make Your First Version Available to the Public
  • Updating the project directory trunk
  • Tagging a new version on the server
  • Updating your local project directory with the new tagged version
  • Updating the readme.txt stable tag
• New Developments for Your Plugin

Getting Started with Your Plugin

Whether you just have an idea or are nearly finished with version 0.1, you need a name and description for your plugin. Make the name short and descriptive, giving some idea what the plugin does. “Wax on Wax off Plugin” is not a good name. “Drop Shadow Maker” is much better. You don’t need to add “Plugin” to the actual title.

To go along with your title, you should write a short description telling people what benefits your plugin provides. I recommend this description be under 150 characters.

Register for a WordPress.org Account

If you do not already have a WordPress.org account–used for interacting in the support forums and the like–you need to get one. Simply go to: https://login.wordpress.org/register

Request to Put Your New Plugin in the WordPress Plugin Directory

Most reasonable plugins delivered with a compatible license can get space in the WordPress Plugin Directory.

1. Go to: http://wordpress.org/extend/plugins/add/
2. Fill in your Title and Description
   (I told you you would need that!)
3. Skip the uploading of your plugin from this form–even if your plugin is ready to go.

Your plugin directory request is processed by real people, so it might take awhile.

Install an SVN Client for Your Machine

To work with the Plugin Directory, you need a Subversion client on your machine.

• For Windows, I recommend TortoiseSVN.
• For Mac, it seems SCPlugin is a good package.

Just choose one and get it installed. There’s not much more to say about that.

Choose a Local Directory for Your Projects

Subversion will be keeping a local copy of your plugin files up-to-date with the WordPress Plugin Directory. I recommend creating one directory on your local machine where you will keep all your Subversion-tracked projects. Caution: If you have a web development environment on your local machine, do not be tempted to use your local web server’s WordPress plugins directory as your project directory.

For example, if you have a local WordPress install on your machine where the plugins folder is:

documents/public_html/devdomain.com/wp-content/plugins/

…do not think you can use that directory to sync your WordPress Plugin Directory projects. That will cause you pain.

Instead, create a directory like this example:

documents/projects/wp-plugins-public/

Each of your plugin project folders will go within “wp-plugins-public.” For this tutorial, I’ll use a plugin folder named “content-scheduler.” So, I will have made a directory as such:

documents/projects/wp-plugins-public/content-scheduler

Your Plugin Request Approval Email

Once your plugin request has been approved, you’ll receive an email with a link to your SVN repository. This is specifically for that one plugin, and is needed to proceed with your Subversion syncing.

Directory Terms for This Article

With so many different directories, projects, and folders mentioned in this article, it could be easy to get confused. Let’s agree on three different locations when working with this Subversion workflow.

1. Working directory
   This is the current copy of code you are changing and testing. It should be in the “/wp-content/plugins/” folder on your development web server. On my machine, it happens to be:
   documents/public_html/devdomain.com/wp-content/plugins/content-scheduler/
2. Project directory
   This is the directory your Subversion client will keep synchronized with the WordPress Plugin Directory. On my machine, this is:
   documents/projects/wp-plugins-public/content-scheduler/
3. Server directory
   This refers to your project as stored in the WordPress Plugin Directory. This is where the public will be able to get your plugin. The root location is called your “SVN repository,” and will be assigned to you in your plugin request approval email. For my example, this is:
   http://plugins.svn.wordpress.org/content-scheduler

Pulling the New Server Directory to Your Local Machine

Even though you haven’t put any files in your new plugin location in the Plugin Directory, you need to pull down that copy of the directory to your machine. Doing so sets some flags behind the scenes to help your Subversion client know what’s up-to-date and what’s not.

1. Right-click your project directory plugin folder.
2. Choose “SVN Checkout.”
3. Enter your WordPress SVN repository URL (from your approval email) into the first field.
4. Your project directory plugin folder should be in the second field.
   Since you started this process by right-clicking that folder, this field should already be populated.
5. Click “OK”

Finish Developing Your Plugin

Develop and test your plugin. This includes creating a proper “readme.txt” file to go along with it. The “readme.txt” file is not just some random notes about your plugin. The WordPress Plugin Directory uses the contents of the “readme.txt” file to understand which version of your plugin is considered current, and also to build the contents of your plugin’s page in the Directory.

• For more information on creating a proper “readme.txt” file, see this WordPress readme.txt example.

An essential part of your “readme.txt” file is the “Stable” tag. While you’re developing your plugin, leave this tag reading “trunk.” Once you release a version for public consumption, we’ll update that with the correct version number.

Make Your First Version Available to the Public

Updating the project directory trunk

1. Copy the contents of your working directory into the “trunk” folder of your project directory.
   In my case, I’m copying the entire contents of my plugin from working directory:
   /documents/public_html/devdomain.com/wp-content/plugins/content-scheduler/
   to my project directory:
   /documents/projects/wp-plugins-public/content-scheduler/
2. Right-click the “content-scheduler” plugin folder in your project directory and choose “SVN Commit.”
3. Enter a comment for the commit if you want.
4. Review the list of files that are considered new and will copy to the server. If this list looks accurate, click “OK” and the files will be copied to your server directory at wordpress.org.

Tagging a new version on the server

You’ve updated the files in “trunk,” but this is not what the public should be downloading. You need to use “tagging” to create a copy of “trunk.” This copy will not be changed any further, and will be offered up for public use. For this example, let’s create a version 1.0.

1. Right-click on the project directory’s “trunk” folder and choose “Branch/Tag.”
   For me, this is:
   /documents/projects/wp-plugins-public/content-scheduler/trunk/
2. The “To URL” location field will end in “/trunk.” You need to change this to “/tags/1.0” to create your version 1.0.
3. You can add a note about this tagging operation if you want.
4. Click “OK,” and ignore any message about “important to change to this branch…”

Updating your local project directory with the new tagged version

You just told the server to make a new copy of your project files in the “/tags/1.0” directory. Now, we need to bring your local project directory up to date with that new tag.

This process might seem strange. You may wonder why you can’t just make your own copy in your local “/tags/1.0” directory. If you do that, the server directory and project directory can get messy and confused about what’s updated and what’s not.

• Right-click the project directory again and choose “SVN Update.”
  This pulls changes from the server directory to your local project directory. In this case, the change is an addition of the “/tags/1.0” copy of your files.

Updating the readme.txt stable tag

All the right files are in place for the public to use your plugin. However, we have to tell the Plugin Directory which tagged version the public should use.

1. Edit the “readme.txt” file in your local project directory’s “trunk” folder.
   For me, this is the following:
   /documents/projects/wp-plugins-public/content/scheduler/trunk/readme.txt
2. Change the “Stable tag” to your release version, “1.0”
3. Save the file
4. Right-click the “readme.txt” file you just updated and choose “SVN Commit.”

That’s it! In 15 minutes or so:

1. The WordPress Plugin Directory will update your project listing
2. “1.0” will be seen as the stable tag
3. The information in “/tags/1.0/readme.txt” will be used to fill out your project’s page.

New Developments for Your Plugin

Most likely, you’ll make improvements to your plugin and need to publish them. Here’s how this works.

1. Make changes to the plugin in your working directory.
   These changes should include changes to the readme.txt file as needed, such as Changelog entries.
2. Copy changes from your working directory into your local project directory.
3. Make sure the readme.txt file has the correct “stable” tag for the current public version.
4. Right-click the project directory and choose “SVN Commit” to get your new trunk changes into the server directory.
5. Right-click the “trunk” directory in your project directory and choose “Branch/Tag” to create a new version tag for release. (Make sure “Create copy within the repository from:” is set to “Working copy.”)
6. Right-click the project directory and choose “SVN Update” to pull down tag changes from the server directory.
7. Update the stable tag in the project directory’s “/trunk/readme.txt” file to match the new release tag you created.
8. Right-click the project directory (yes, one more time) and choose “SVN Commit” to get your updated readme.txt file to the server.

Phew. That’s all!