How to Publish a WordPress Plugin – Subversion

After a discussion on the WordPress Answers Stack Exchange yesterday, I thought it would be a good idea to explain the different ways you can develop plugins for WordPress.  Since the official plugin repository uses Subversion for version control, that’s the obvious first choice when you’re just starting your development stack.  So here is, step-by-step, a tutorial on how to get started using Subversion to track changes in and eventually publish your WordPress plugin.

Things you’ll need to follow along:

  • A WordPress plugin to write
  • TortoiseSVN (Mac users see my note about SCPlugin)
  • A WordPress.org account

First and Foremost

The very first step is to create an account on WordPress.org.  You’ll use this account to control your plugin, post to the support forum, and edit the Codex.  Chances are that you already have an account.  But if you don’t, it would be a good idea to create one.

Get Hosted

Next, you’ll need to ask the WordPress.org team to host your snazzy new plugin.  All you need at this point is a name and an idea.  It can take anywhere from an hour to a few days to get your application approved, so don’t worry if you don’t have any code written yet.

Using Subversion

Using version control is the first lesson every developer should learn, unfortunately it’s often a lesson learned through painful experience when something goes wrong.  Let me tell you this, being able to “undo” a bunch of changes you’ve made over several folders is an ability worth its weight in gold – assuming it weighed the same as a 600-lb gorilla.

If you haven’t used version control yet, you should start.  Now.  Right now.  Which is convenient, because we’re going to!

If you haven’t done so already, download TortoiseSVN.  It’s a Windows GUI for Subversion that allows you to do all the fancy version control you need to without ever having to touch the command line.  Purists might tell you to start with the command line first, but I know how intimidating that can be … so we’ll start with the easy-to-use GUI instead.

A Note for Mac Users

Unfortunately, I don’t have a Mac, so I can’t give you screenshots or a guided walkthrough of a commit process.  However, I have it on good authority that SCPlugin provides the same functionality with a very similar UI.  The pictures won’t look the same, but you should be able to follow the same steps as outlined below.

Check Out the Repository

Let’s say your plugin application has been approved and you’ve finally received the “go ahead and get started” email from the WordPress team.  Great!  Find a place on your computer where you want to keep your plugin, and create a new folder for it – I keep most of my stuff inside a “/WP-Plugins” folder.

Right click inside the folder and select “SVN Checkout” from the dropdown menu.  Put the URL for your repository in the first box and make sure you have a folder name specified in the second box.  Most likely something like “/WP-Plugins/my-cool-plugin.”

Now you’ll have an empty repository ready and waiting for your plugin.  If you open the folder, you’ll see three sub-folders: branches, tags, and trunk.  We’re going to do all of our development in trunk.

Create a First Version

If you’ve already got your plugin ready to go, great!  It’s actually easier to start using the repository for version control after you submit a first version.  So let’s assume that you’ve finished your first beta release (version 0.1) and are ready to release it.

Copy your entire plugin into the trunk folder.  All of your PHP files, your images, your stylesheets, your JavaScript, and your readme file.  Everything.  Then right-click anywhere in the folder and select “SVN Commit” from the TortoiseSVN menu.

You’ll be presented with the commit window.  Enter “First commit of My Cool Plugin” for a commit message, select the checkbox next to each of the new files, and click OK.

Tortoise will think for a few seconds while it talks to the WordPress server.  Then it will ask for your WordPress.org username and password (to make sure you have the right to commit to your plugin).  Enter these and click OK.  Then, voila!  Your plugin is in the repository.  Well … almost …

Tag Your Release

The WordPress.org plugin repository uses version tags to control everything.  Basically, the engine looks at the readme file in /trunk, reads the “stable tag” out of the file, then loads the rest of the plugin from that tag in the /tags folder.  So until you tag your release, you haven’t really published your plugin.

Right-click in the folder again and select “Branch/Tag” from the TortoiseSVN menu.  This brings up the tag dialog window.

The first line in the dialog should indicate that you’re in the /trunk folder (the last word in the URL should be “trunk.”  In the “To URL:” field, change “trunk” to “tags/0.1″ assuming you’re releasing version 0.1 of your plugin.  Enter a commit message – along the lines of “Tagging version 0.1″ – in the big box at the bottom and click OK.

A window will pop up explaining that you’ll need to switch to the new branch to work on it.  Ignore this message, you won’t need to switch to anything.

Now right-click in the folder one more time and select SVN Update from the TortoiseSVN menu.  This will update your local /tags directory with the tag folder you’ve just created.

That’s it.  You’re done.  Your plugin is published.  But what comes next?

Making Changes

From here on out, you can change anything you want in the /trunk directory and commit it except for the readme file.  You can update the readme file, but do not change the “stable tag” reference until you’re ready to release!

Let’s say you need to add a new JavaScript file to your plugin, but it needs a lot of work.  Go ahead and add it to /trunk and commit the changes (you’ll be asked for your WordPress.org credentials again to commit).  Do some more work on the plugin, update some stylesheets, whatever.

Then, when you’re ready to release version 0.2, you need to do three things:

  1. Update the “stable tag” reference in the readme file.
  2. Update the version number in your plugin’s main PHP file.
  3. Tag the new release.
  4. Commit the new release.

Updating the stable tag is easy.  Just change it in Notepad and save the file.  Then right-click in the folder and select “Branch/Tag” as before … with one difference:

TortoiseSVN will warn you about taging your local version that’s not a HEAD revision.  So to keep from making an out-of-sync branch, be sure to check the “Working copy” option in the “Create copy in the repository from:” section.  Then tag as a new version just like you did with 0.1 above.

This will create a new folder in the /tags folder for your new version and copy the latest changes you’ve made over to it.  But you’re not done yet!

Now, right-click and select SVN Commit to commit your changes to /trunk

Why Did We Tag First?

Remember, the WordPress repository looks at the readme file to find the right version, then looks for that version in the /tags folder.  By committing our tag before committing the changes in the readme file, we guarantee that the right version of the plugin will be there before WordPress needs it.  Basically, you made sure /tags/0.2 existed before submitting a readme file that told WordPress to look for it.

Comments

  1. says

    Hey Eric,

    Thanks for the highly helpful tutorial. I just followed this to publish my first WP plugin and it was an absolute lifesaver!

    Cheers,

    – Kezz

  2. says

    Hey Eric,

    Brilliant post. It helped me alot. I followed exactly the same steps as mentioned by you to update a new version of my plugin. But for some reason, no notification is send to existing plugin users nor the new version gets updated on the wordpress download plugin screen. But when you download the plugin, the latest tagged version is downloaded.
    I am really confused now. dont know what is going wrong. Can you please help me?

    this is my plugin http://wordpress.org/extend/plugins/kc-related-posts-by-category/

    • says

      Notifications aren’t supposed to go out. WordPress will automatically check with the repository twice per day to see if a new version is available. If there is (if the version in the repo is > the version on the site), it will alert the administrator and ask them to update.

      I didn’t see a problem with your plugin as far as its location in the repository or its tag structure, but WP isn’t recognizing anything beyond version 1.0. I suggest emailing plugins [at] wordpress [dot] org and asking them to take a look …

      • says

        Hey Eric,

        Really appreciate for taking out time and having a look at the plugin. I have emailed them and waiting for the response.

        But I guess I followed your document for updating the plugin. While uploading it for first time, I have followed some other document and it went wrong.

        Now for second plugin, I followed your document and everything seems to be perfect. Wish I had done the same before.

        Thanks alot for your help. Really appreciate..

      • says

        Hey Eric,

        I found out what mistake I was doing. The actual version shown on the download page is picked from main .php file of the plugin. So in the top we usually specify the version field.

        I was not updating that value and hence it was still showing the old version.

        Thanks again for all your help.

        • says

          Hey kunal, I found this post very helpful, even i followed the same steps to update my plugin to newer version, but fortunately even i made same mistake as you did. I forgot to update the version in the main .php plugin file and now it is not showing the new version on the download button of the plugin page on wordpress. But when you download the plugin it is of newer version. Plugin URL – http://wordpress.org/extend/plugins/shortcode-collection/

          Any Help is much appreciated!!
          Waiting for your reply.

  3. says

    I am having the weirdest issues and found your blog. i went through and now know we where doing things correctly…BUT..lol no luck.

    Followed your instructions and i KEEP getting the same error onb checkout *(below)..BUT he did exactly the same (on Linux) and it worked, fyi i am on Windows 7

    this is the error that KEEPS coming up after trying to checkout.

    Checkout from http://plugins.svn.wordpress.org/wp-online-store, revision HEAD, Fully recursive, Externals included
    ‘http://plugins.svn.wordpress.org/wp-online-store’ isn’t in the same repository
    as ‘http://plugins.svn.wordpress.org/’

    any thoughts would be a lifesaver.

    Garfield

    • says

      Unfortunately no, I have no idea what’s going on. And to clarify, I actually wrote this tutorial using the same steps I follow on my Windows 7 box when I update plugins. And I’ve verified a few weeks ago that things are still working (for me at least) when I helped another developer update their system.

      The only thing I can think of is that maybe your Tortoise installation is broken. Maybe try to re-install Tortoise and try again? But I’ve never seen that error message before …

  4. says

    I find your post one of the most clear I found, and yet, there are so many steps!

    I still have questions, though, because so many people saying “just do the changes locally and then “add” and “commit”… gave me so many bad experiences trying to un-do every trial and error… Adding a new folder (tag) that I got by duplicating the previous tag only gives me MORE NIGHTMARES! (Error: “This or that already versioned”

    The screenshot Tag1.png shows in both “from” and “To” the same local trunk. And then you say “click in it again”, and I don’t know what you are refering to.

    Could you explain?

    Also, when I copy the whole folder or files from the trunk to a new tag (folder?) in the respository, there’s no command that works for copy/update/checkout the copied files to the local computer.

    I use RapidSVN, but I tried before with another applications and same issues.

    Once you are used to windows and folders, GUIs like these are not intuitive enough to make you feel like adopting it.

    • says

      Regarding the screenshot. That’s the dialog box that appears when you first right-click and then select “Branch/Tag.” You have to click the “To URL” field and edit it to change /trunk to /tags/0.1 (assuming you’re tagging version 0.1).

      If you’re tagging, try to avoid copying the entire /trunk directory anywhere. It has hidden /.svn folders inside it that Subversion uses to track individual file revisions. That’s why you’re having issued with the “This or that already versioned” message.

      If at all possible, use Subversion to create the tag rather than trying to move any directories or files yourself. It’s more efficient to use the GUI tools than to do it manually. I recommend TortoiseSVN because it integrates well with Windows and the regular directory structure and doesn’t require you to learn command line functions.

  5. Cezar says

    Very useful tutorial.
    I am having a weird issue and found your blog.
    I’m a little confused about submitting a plugin. I have two small plugins that I used for a few months, and I decided to give them to others. I tried a couple of times to send them but the only thing that I get is a email containing “This plugin will not be included.”.

    The plugins are: http://www.greatwpplugins.com/easy-post-subtitle/ and http://www.greatwpplugins.com/extra-category-content/.
    The plugin name is unique.
    I have no idea why they rejected my plugins.

    Any thoughts would be a lifesaver.

  6. Jonny says

    Very very helpful tut.
    All was going well…

    I have a problem… if you can shed some light, would be much appreciated.

    I get to the stage… Tag Your Release
    The part ‘From WC to URL’ it shows in your screenshot a file referenced on the C drive.
    When I get to this stage I only have http://plugins.svn.wordpress.org/….. and cannot select hard drive.

    I tried keeping it as the http but when pushing, it does create a folder version 1.0 but inside this folder, instead of the files it contains a duplicate – branches, tags, trunk.

    Anything obvious that might be going wrong?

    Many thanks

    • Jonny says

      A short followup…

      The following line “Right-click in the folder again”… i found i had to ensure i right clicked inside the trunk folder. The previous right click mentioned was in the master folder.

      I still had the reference to http and not C:// but it has seemed to work ok.

      I guess this is solved.

      Thanks again for the help!

      • says

        Actually, you did that just fine. The reference should be to the http location of the directory. In my example, I was committing instead to a local repository rather than a remote one. So you’re doing everything the right way :-)

  7. Jon Hudghton says

    Just wanted to say thank you for the fantastic guide! Had my first WordPress plugin approved and was kind of stuck how to set up svn on my home Windows PC and get it working properly, but your steps made it a breeze.

  8. Sonya says

    Just in case anyone has the same problem as I just had:
    If you are working on a Mac (snow leopard, dunno about the new release) and having trouble using the SCplugin suggested here because of a SSL error during checkout (url not secure, not trusted), please try the following:
    Open terminal
    Type in: /usr/local/bin/svn ls https://……
    (and that’s a lower-case L, not a capital i, before the https:// part)
    It will ask you if you want to temporarily or permanently accept the “fishy” SSL. Type ‘p’ for permanent. Then go back to the checkout process from the SCplugin menu and complete your data transfer as outlined in Eric’s post.

  9. says

    I managed to get my file updated but I can’t anything to go into the local tags file. Something is missing from your instructions or I just don’t get it.

  10. says

    You are missing a step in your “make changes” section – perhaps you meant to express it but it was not explicit enough for me (given I have made the same mistake multiple times now).

    In order to get all the version information lined up, you also have to update your version number in whatever your main php file is. Otherwise your current version on your wp.org/plugins screen (a.k.a Download version 0.2 etc.) won’t match your changelog and or readme.txt file. It’s annoying as heck to make a change only to find your forgot the grrrrr version number in the main program file.

  11. Arya says

    Thanks for posting this, I just follow the guideline step by step.
    Anyway, how to add header background and screenshot? (at plugin page)

    Thanks

    • says

      That can catch a few people up. Just remember, the commit message is the only way you (and the rest of the world) have to know why you made those particular changes when you come back 6 months later and look at the logs.

  12. says

    I have tried this 50 times and can’t get it to work. When I put the plugin files into the folder they all have a blue question mark … then when I right-click and click commit it says “no files were changed or added since the last commit”.

    This is driving me up the wall … everyone else seems to be able to get it to work. Depressing.

    • says

      That’s entirely understandable. The problem is that the files are “unversioned.” Basically, Subversion doesn’t know they exist. There are two ways to “add” them to Subversion. Way 1) Right click and select Commit like normal. Then, when you see the list of files in the commit window, right-click any that have a status of “non-versioned” and select “add” to add them to Subversion. Now when you commit they’ll be checked in.

      If there are a lot of files, you can right-click the files themselves in Explorer. From the Tortoise SVN context menu, select “Add” and they’ll be added to Subversion. From here, you can commit as per the regular instructions.

      • says

        Thanks for your reply eamann – I finally got the plugin uploaded and just can’t get the header banner to show. Have it in the assets folder and am getting a colleague to check out my repo.

        • says

          I wish you the best of luck! Having someone else take a look at your repository is the best way to make sure everything is in the correct location. My first attempt accidentally put /assets inside the /trunk directory … that won’t work, they need to be side-by-side.

  13. says

    Thanks for the help on this one, I am a newbie to SVN. Finally got my first plugin published, BuddyPress Profile Tabs. The best tutorial I found for this specific task, I didn’t think I’d find any tutorials at all. Nerd props to you my friend.

  14. says

    Thanks for a great walkthrough. Worked great for me except one idiot error I made. When TortoiseSVN prompted me to put my WordPress.org username and password. The username is case-sensitive.

    I’ve uploaded my first plugin, MU Plugins Tool. It allows you to selectively enable/disable any must-use plugins installed.

    Thanks again!

  15. Rupesh says

    I have follow your instruction but i am getting an below error:

    “Unable to connect to a repository at URL
    ‘http://plugins.svn.wordpress.org/wp-copy-data-protector’
    OPTIONS request on ‘/wp-copy-data-protector’ failed: 408 Request Time-out”

    Thanks,
    Gaurang

    • says

      You might need to update your Subversion client, or you have some strange firewall rules configured on your machine. I just tried connecting to that same URL and things worked just fine.

  16. says

    Hi,

    Thank you for your tutorial, it helps.
    Unfortunatly, I keep having this message while commiting modified files :

    Error running context: The server sent an improper HTTP response

    Do you have any clue on why ?
    Thanks !

    • says

      Without more context, no I don’t know what’s going on. I’d recommend checking StackOverflow or similar sites for that error message.

Trackbacks

Leave a Reply