With the looming release of WordPress 2.0, there are a bunch of folks that are submitting bug fixes that say things like, "I would submit this to Trac, but I don't know how."

I think even more people are suggesting that writing to the mailing list with their bugs to "confirm" them is better than submitting them directly to Trac.  I suppose if you're not sure something is a bug, it might be worthwhile to ask someone else (I would ask on IRC at #wordpress on irc.freenode.net) but it really is better to have a formal record of an issue, even if it turns out that what you're experiencing is expected behavior.  If you really fear that it's something to do specifically with your installation, check on IRC or maybe try a fresh install.  Nevertheless, it might be useful to folks to learn how I do it.  I'm not saying my method is correct, just that it seems to get the job done with few complaints from the devs who commit my patches.  It's also a good method to use on Windows.  (Sorry, someone else can document command-line Subversion use - not that I don't know it, I'm just lazy.) Here we go... 

Here's what you need to do to get an environment that is ripe for making source modifications:

  1. Get a WordPress.org Support Forum Login - You need a support forum login to gain access to Trac.  Trac is the software WordPress uses for bug tracking, and it shares its login database with the support forum.
  2. Download and Install Tortoise SVN - Tortoise is the best Subversion client for Windows.  It will let you get the latest source from the code repository without messing with funky nightly versions.
  3. Install XAMPP - If you're not already running Apache locally, you're going to need it.  You can test under Microsoft's IIS (and this is probably not a bad idea considering there are fewer people testing that environment) but if you're not running Windows XP Pro (not Home), you may find this difficult.  XAMPP is Apache, MySQL, PHP and some other thing you don't need for WordPress all rolled into one bundle.
  4. Checkout a Copy of WordPress - Find the directory that XAMPP is using for its DocumentRoot and right-click on it (or create a "wordpress" directory there and right-click on that).  Select SVN Checkout....  In the dialog, use http://svn.automattic.com/wordpress/trunk as the repository URL.  Click OK to download the latest WordPress source.
  5. Make a Database - Use phpMyAdmin to create a new database for WordPress.  Navigate to http://localhost/phpmyadmin to see the interface.
  6. Run the WordPress Install - I trust you already know how to do this.  If not, then perhaps patching is a bit advanced, no?

Ok, now WordPress is running.  You should be able to do anything that you normally do with WordPress.  At this point, you can modify code freely.  If you make a change you don't like, you can always switch back to the original code.  Right-click on the file, choose Tortoise SVN > Revert and the file will be restored to the last checkout version.  You should be able to see where you've made changes to the source by looking at the icon for the folder/file.  The ones that are changed will likely be red.  Here's what you need to do to make a patch:

  1. Update your source - This step is pretty important, otherwise you might end up patching bugs back into source that's already fixed.  Subversion has integrated merge features.  All you need to do is right-click on the wordpress root folder and select SVN Update.  If any of the files you edited come up as conflicted (in red in the list), you will need to merge them by hand in the tool provided when you double-click on the list item.
  2. Create a patch - This is easy.  Right-click on the wordpress root folder and select Tortoise SVN - Create Patch.  A dialog appears to allow you to select the files you want to include in the patch.  Check the files you want to include, then save the patch file.  If I'm patching one file, I'll usually use the full name of the file followed by ".diff", for example, "admin-functions.php.diff".
  3. Find a Trac Ticket - To submit a patch, you need a ticket.  Be sure to search for an existing ticket for your issue before creating a new ticket.  If one doesn't exist, create one and explain the problem as clearly as possible.  When you have a ticket, click Attach File and attach your patch file.

That's pretty much it, even though I'm sure I've left some trivial things out.  The essential bit to recognize is that there really isn't a good excuse for a developer to know enough to make code changes but not enough to use source control.  If you don't know source control, consider that learning this simple task is a great way to pad your resume.  One way to scientifically demonstate that you can work well with teams is to show a proficiency with source code conrol tools.  Hopefully this short description will help you on your way. 


Should've been titled "How To Patch WordPress on Windows".

I guess you're assuming that Linux users know how to use the svn CLI client, eh?

Most people who are not submitting bugs because they don't know how to create patches are on Windows.

If you already have Subversion installed on Linux, then you probably already have an Apache instance running and know how to create a database for WordPress. So you only need to know how to use the command-line Subversion client.

To checkout a copy of WordPress to the current directory using the command line:
svn co http://svn.automattic.com/wordpress/trunk

To update the working copy of WordPress in the current directory:
svn up

To create a diff of a specific file or directory in the working directory:
svn diff {file/directory name} > patchfilename.diff

Everything else is the same.

Two points remain:

1) I have no idea how to install Subversion on your version of Linux. I suppose there's a package or something, but you'll have to figure it out since I'm not going to write instructions for each distribution's installer.

2) Next time, you write the instructions. Damn, I spend an hour writing a post with detailed instructions, and this is what I get.

Ooohhh, thanks! Really a good tutorial, although the post title is a tad misleading... I was hoping for some instructions for creating a magical "Click here to upgrade all your various Wordpress installs with absolutely 0 problems - instantly!" button. :)

Now where were you and your xampp goodness a month ago when I installed all that crap manually?

Anyone else find a SVN client named Tortoise ironic? Look, I know I'm a little slow with some of my projects, but really...

I wasn't trying to be harsh. Guess it came across that way. I definitely appreciate all the hard work you obviously put in to the post.

I'm a professional Systems Admin, so I deal with a LOT of engineers running Linux that don't necessarily know the ins and outs of a CLI, let alone how to use the svn commandline client. Bumped over to this post from the Dashboard of my WP install thinking that it would be a bit more generalized.

So please accept my apologies, no offense was intended by my comment. Keep up the good work.

Excellent info! I didn't even know about XAMPP, and now I'm using it to mess with my WP site without actually having to do it live at 2am so no one see it. :) Thanks very much!

I love you. *sheds a tear*

Seriously, I've been wanting to try and figure out how to not be a noob for quite a while and now I know how! Thanks SOOOO much! :D

Sorry, commenting on this post is disabled.