This article is meant to supplement WordPress’ Using Subversion Guide. Whenever I mention the guide I am referring to this.
So you’ve written a WordPress plugin and its now time to upload it to the WordPress plugin repository. Your first step will be requesting that your plugin be hosted on WordPress’ Plugin Directory. Sometime later your request will be accepted (provided it doesn’t drop all of the tables in the database or something like that) and you’ll be given access to the Subversion Repository.
If this is your first time making a WordPress plugin you might have no clue what subversion is, much less how to use it. WordPress provides some good Documentation on this subject, but I think there are a few things they left out that could be useful to someone using doing this for the first time.
Reading through WordPress’ Using Subversion guide will probably give you a pretty good idea of what subversion is, but by the time they get to actually using subversion you might be a little lost. I’ll pick up at the point I think it begins to get a little fuzzy:
Task 1: Starting from scratch with your brand new plugin repository
This section begins with a short overview of what you will be doing:
- Check out the blank repository.
- Add your files to the
trunk/ directory of your local copy of the repository.
- Check in those files back to the central repository.
Then they toss a blob of text at you.
# Create a local directory on your machine to house
# a copy of the repository.
$ mkdir my-local-dir
# Check out the repository
$ 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.
# As you can see, subversion has added ( "A" for "add" )
# all of the directories from the central repository to
# your local copy.
# Copy the plugin files to the local copy.
# Put everything in the trunk/ directory for now.
$ cd my-local-dir/
my-local-dir/$ cp ~/my-plugin.php trunk/my-plugin.php
my-local-dir/$ cp ~/readme.txt trunk/readme.txt
# Let subversion know you want to add those new files
# back into the central repository.
my-local-dir/$ svn add trunk/*
> A trunk/my-plugin.php
> A trunk/readme.txt
# Now check in the changes back to the central repository.
# Give a message to the check in.
my-local-dir/$ svn ci -m 'Adding first version of my plugin'
> Adding trunk/my-plugin.php
> Adding trunk/readme.txt
> Transmitting file data .
> Committed revision 11326.
# All done!
There are a few things you should know about the commands above. To begin, these commands should be entered on a unix shell. If you are familiar with unix you already know that text following the # symbol are comments and the text following the > symbol are the shell’s response to the commands. The commands themselves are not preceded by any symbol.
Another thing you should know is that the writers assume that you already have subversion (svn) installed. If you don’t like the idea of using a command line to access and modify the repository, there are a lot of GUI programs out there. You can find a listing of third party clients on the Subversion Website From this point on, however, I (and the writers of the guide I am referring to) will assume you have access to a unix command line with subversion installed.
If you are a windows user and don’t have access to a unix shell, I suggest using cygwin. SVN is part of the cygwin package, but you must explicitly specify that it be downloaded and installed. Read the cygwin documentation for more information. To test whether or not SVN is installed, type svn help in the shell.
Now that you have access to UNIX with SVN installed you should have no trouble running the commands in the guide.
Task 2: Editing a file that is already in the repository
Once you’ve uploaded your initial version, you will almost certainly need to make changes to those files sometime in the future. The guide is pretty clear on how to do this, so I will just provide a brief summary of the commands you will use for this.
svn stat shows you a list of files that differ from those in the repository.
svn ci -m "my message" updates the files in the repository with your local copies. It does not automatically add new files or remove old files. If you have added a new file that did not exist before you will have to use the svn add command to manually add this file. Likewise you will have to remove a file manually with the svn remove command. Documentation on any command can be obtained by using the svn help [command] command, where [command] is replaced by whatever command (ie add, remove, stat) you need documentation on.
Notice that the first command issued before updating any files is cd my-local-dir. It is very important that you are in you plugin directory when using any of these commands.
Task 3: “Tagging” a new version
Tagging refers to assigning a version to your plugin. Whenever you create a new version of your plugin you will need to tag that version. As the guide mentions, you do this by using the svn cp. It is important that you use the svn cp and not the normal cp command to do this. svn cp just doesn’t copy the files, it also adds the files as you would using the add command.
It is important to note that the command svn cp trunk tags/0.1 assumes that the folder 0.1 does not exist in the tags folder. You won’t get the desired result if it already exists.
As the guide mentions, it is important that the readme.txt file in your trunk folder is updated with the proper stable tag BEFORE copying the files.
Some Important Notes
Do not add, remove, move, or copy files with the normal commands (or through a GUI). To do these things you must use the svn [command] (ie svn add, svn move).
Stick to one application for managing your repository. It is not a good idea to use one program to add and remove files and then another to attempt to update the repository.
You can use whatever editor you want to modify your files. The example in the guide is nano trunk/my-plugin.php, but you don’t have to do everything from command line. Personally I use notepad++ to make changes to my files, just refrain from doing anything other than editing from your GUI or third party app.