Planet WordPress

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.