How to submit a patch to WordPress core (for beginners)

WordPress Patch File

It took me a few years, but I finally arrived at a point where I saw a need for a change in the WordPress core and felt comfortable enough with code to make it happen myself.

However, unless you’ve used version control, and specifically Subversion, before, the whole process of editing WordPress core and submitting a patch can be daunting to say the least, so I wanted to document how I did it here, for you to use.

The first thing you’ll need is a Subversion client that supports creating patches. WordPress suggest TortoiseSVN for Windows (free) and Cornerstone for Mac (not free). I’ll be using TortoiseSVN for this tutorial.

Installing TortoiseSVN

So, I found TortoiseSVN and installed it. Then, you’ll have to have a local web server installed on your machine so that you can run and test WordPress.

For a more detailed tutorial on how to install and use local web servers, look at these tutorials for using MAMP (Mac) or XAMPP (Windows)

Create a folder inside your local web server called wordpress-svn (probably C:/xampp/htdocs/wordpress-svn for XAMPP on Windows).

With TortoiseSVN installed and your wordpress-svn folder created, right-click on the wordpress-svn folder and choose TortoiseSVN > Settings. Go to the Context Menu section and check the following options: Checkout, Update, Show log, Repo-browser, Create Patch and Apply Patch. Click OK.

Downloading the source code

Now TortoiseSVN is set up and ready for you to download the source code from WordPress. Right-click on your wordpress-svn folder and choose SVN Checkout. In the dialogue window that pops up, choose as the URL of repository and click OK. TortoiseSVN will then start downloading the entire WordPress codebase, which will take a minute or two. Once it’s complete, you’ll notice the familiar WordPress file structure inside your wordpress-svn folder.

SVN Checkout for WordPress

Getting WordPress operational

You can now edit wp-config.php and set up your pertinent database details for a new database that you’ll create just for your development version of WordPress.

Once you’ve done that, be sure to set WP_DEBUG to true in wp-config.php, since you’ll want to be notified of any issues. Then use your web browser to navigate to your local wordpress-svn folder to run the WordPress installation script and complete installation of WordPress.

Now you’re in a position to edit any file you like in WordPress. This depends on what issue you’re trying to patch, or what improvement you’re trying to make, so this is where you take over for a while.

Update the source code often

Unless you make your edits immediately after you download the source, you’ll want to update your source code to make sure that you’re editing the most recent files. Periodically, go to your wordpress-svn folder, right click and select SVN Update.

Creating your patch

Once you’ve made all of the edits that you want, you’ve tested it and you’re ready to submit the patch for testing and review, right click on the wordpress-svn folder and select SVN Create Patch.

Creating a WordPress patch

The subsequent window will show a list of all files that have changed since you updated the source code, which should essentially amount to the files that you changed. If others appear in the list, which do not apply to the edits you made (such as wp-config.php), you can uncheck those to make sure that they are not included in your patch.

Once you have selected all the right files, click on OK and select where to save your patch file. TortoiseSVN will then open the patch file, which essentially shows the differences between the original files and how you added to/modified them.

WordPress Patch File

Submit your patch

Congratulations! You have created your first patch. Now you need to submit it for review by the core developers.

The process for submitting patches uses the Trac system, which is used for reporting bugs within WordPress.

Depending on what your patch is, you might be fixing a bug, or you might be making an enhancement to WordPress. Once you’ve logged in using your account, search existing tickets to make sure that someone hasn’t already reported the issue you’re patching, or suggested the feature you’re adding.

If they have, review their ticket and see if your patch will solve the issue they have described.

If you can’t find a ticket that matches your feature suggestion or bug, create a new ticket and explain in detail the feature/bug.

For a better explanation on the fields you need to fill out when submitting a ticket, see this guide.

Each ticket has the ability to attach files to it, which is where you need to upload the patch file you just created.

Trac ticket with patch attached

Once you have updated the ticket with your patch, you can use the RSS feed, or email subscriptions to stay updated on the progress of your ticket. With any luck, it will be reviewed and committed, and you’ll become part of an elite group of WordPress contributors.

5 thoughts on “How to submit a patch to WordPress core (for beginners)”

  1. Piet says:

    Awesome, Dave! Would you also have something like this using the SCPlugin on Mac? I’m ready with my patch, just no clue on what the next step is. In the dropdown menu of the SCPlugin there is no such thing as “SVN Create patch”…

    1. I’m afraid I’ve never used SCPlugin: I use Cornerstone on the Mac. If you figure it out, please let us know how you did it.

      1. Piet says:

        I managed to do it via the terminal command `$ svn diff > 00000.patch` (where 00000 is the ticket number) and then uploading the diff to the ticket on trac.

        Have you upgraded to OSX Mavericks already? And Cornerstone still works? I’m asking, because SVN via terminal has completely fallen apart. Mavericks uses svn 1.7 while the WordPress svn is (still) on 1.6 which are seemingly incompatible.

        I had to use a Mac that I haven’t updated and I probably won’t as long as there is no solution. Any tips more than welcome!

        1. No, I’m afraid I haven’t used Cornerstone since upgrading to Mavericks. Interested to see if it still works now!

  2. Andy Mercer says:

    Very much appreciate this tutorial! I have been interested in contributing for a while but it always seemed overly complicated. Thanks to this I was able to get up and running, and submitted by first patch today.

Leave a Reply