Using Subversion with the WordPress Plugin Directory
Hassan Akhtar   – March 2, 2022
4 Comments

Using Subversion with the WordPress Plugin Directory

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

5WDTz6pPh4Y

These essential steps from the video follow below:

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.

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.

FREE EBOOK
Your step-by-step roadmap to a profitable web dev business. From landing more clients to scaling like crazy.

By downloading this ebook I consent to occasionally receive emails from WPMU DEV.
We keep your email 100% private and do not spam.

FREE EBOOK
Plan, build, and launch your next WP site without a hitch. Our checklist makes the process easy and repeatable.

By downloading this ebook I consent to occasionally receive emails from WPMU DEV.
We keep your email 100% private and do not spam.

  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.

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!

Have you uploaded any plugins to the WordPress Plugin Directory? Share your experience and comments below.

Tags:

Hassan Akhtar Hassan Akhtar is the lead dev for Smush and HummingBird. In his free time he enjoys writing about his development adventures at WPGurus.net.