Submitting patches to WordPress core: the process of creating and sharing changes

If you use WordPress to make a living and tell your story, it’s very exciting to see the changes you write added to the WordPress codebase. I know this is for me.

In this tutorial, you'll learn some of the simple things you need to know to create a WordPress patch that is accepted by the core software.

While WordPress is open source software that anyone can download and modify, only a handful of core contributors are able to commit their changes to WordPress itself. If you want to make a change to WordPress's core files, you can make a suggestion by creating a ticket detailing the proposed change and attaching a patch, or by attaching the patch to an existing ticket.

A patch or diff file is a file that details the changes you have made to your source code and can be used by a version control system such as SVN or GIT to apply your changes. Patches can be easily created from the command line or through GUI tools like SourceTree.

In this article, I will detail how to use the excellent GIT GUI application SourceTree to check for the latest version of WordPress and create a patch file. If you prefer, you can use a GUI tool of your choice or the command line.

Find or create tickets in Core Trac

When you submit a patch to WordPress core, it must be attached to a ticket in the WordPress issue tracker (called trac). Therefore, the first step in submitting a patch is to find or create a ticket.

While it is possible that new tickets with new features will be accepted, it is unlikely. WordPress has millions of users, and it makes sense that major developers would be wary of introducing new features. Almost all new features are now developed separately as plugins first and only merged into the core after extensive testing and development.

The best way to get a patch accepted is to create a patch for an existing ticket. Recently, core trac was redesigned to make it easier to find tickets that have simple fixes and are most likely to be included in the next version and version of WordPress.

Report error

If you want to create a new ticket in core trac (which is a great thing if you find a new bug), you can do that here. Just make sure you search trac for any reports of the same issue before creating a new ticket and verify that the bug exists in the latest version of WordPress.

I am not referring to the latest version, but the master branch in GIT terminology or trunk in SVN terminology. I'll detail how to get the latest version later in this tutorial.

You must at least fill out the Summary field (the title of the ticket) and the Description field, which is the content of the ticket. In your ticket description, be as descriptive as possible.

At the 2013 WordCamp Orlando contributor workshop I attended, WordPress lead developers Mark Jaquith and Andrew Nacin created this list of great bug reports:

• Steps to reproduce the problem (starting with the earliest step)
• wrong description
• What you see versus what you expect
• Error message or error code
• PHP Errors (What are the warnings on the page, what appears in the logs, are there any JavaScript or Apache/nginx errors?)
• What browser?
• Environment (your PHP version, MySQL Apache or nginx version)
• Will this happen without plugin and default theme?
• Screenshots of user interface issues
• Clear and concise
• Let’s get to the topic first, and then explain in detail.
• Related ticket number
• One error per ticket
• Permalink settings
• Do you want to enable multisite?
• WP_DEBUG or equivalent enabled?
• The user role logged in when the problem occurred (or change the role in the database)

Keep in mind that not all of these will be relevant to every error, but the more relevant information you can add, the better.

Unless you are sure what you want to set there, you should leave the fields described below and let core contributors use them to classify tickets accordingly. I recommend using the "Has Patch" or "Needs Patch" tag depending on whether you attach a patch to fix the bug.

View the latest WordPress from GitHub using GUI tools

Before creating a patch for any ticket, it is very important to have the absolutely latest version of WordPress, as many changes are made to it every day. Unless you're using the latest code, it's impossible to know if your fix worked or if the bug still exists. If your patch modifies code that has already been changed, it may not be accepted.

WordPress is managed in SVN, but the code is mirrored as GIT repositories in two locations:

1. git://core.git.wordpress.org/
2. https://github.com/WordPress/WordPress

GitHub repositories are the easiest to use. Keep in mind that even though it's an official GitHub repository, it's still not used for issue tracking, and you shouldn't submit pull requests to it.

There are multiple ways to get the latest version of WordPress via SVN or Git. Personally, I find the easiest way to clone a GitHub image using the excellent GIT GUI tool SourceTree. This is as simple as selecting New/Clone from the File menu, entering the address of your Git repository in the Source Path/URL field, and specifying the local path for the clone, located inside your XAMMP or Vagrant test environment.

Speaking of Vagrant, the popular WordPress Vagrant configuration VVV has a pre-configured test environment for WordPress core, including the latest code and unit tests.

Create patch file

After you have made the changes to WordPress that are required to resolve the issue you are trying to fix and have tested the fix, you will need to create a patch file to upload to a ticket. SourceTree includes a method for creating patch files, or you can use the command line.

In SourceTree, you can create a patch file by going to your working copy and right-clicking on the changed file. Select "Create Patch" from the right-click menu.

Alternatively, navigate to the root of your WordPress repository in the terminal and create a diff using the following command:

git diff —non-prefix ~/name.path

No matter how you create the patch file, you should name it after its target ticket number. If this is the second patch uploaded to the ticket, append .2 to the end of the number, if this is the third, append .3, and so on. For example, the fifth patch for ticket #12358 would be called #12358.5

Upload patches to Trac

Now that your patch is ready, you need to upload it to a ticket in core trac. On any existing ticket, there is an "Attach File" button below the description that you can use to upload a patch. On the next screen, be sure to add a description of what the patch does.

Be patient and understand

WordPress is a massive project, so it's unreasonable to expect an immediate response to your patch. Also, please understand that the standard for patches submitted to WordPress must be very high to best serve all users.

After submitting a patch, please be patient and understanding of any feedback you receive. The main developers are very approachable, if you have questions about a patch or why it's not improved, feel free to ask one of them in the #wordpress-dev IRC channel.

While it can be frustrating to wait for a response and have to make changes, it's worth it when your patch is submitted to WordPress and the changeset description recognizes you.