Function Documentation

WordPress Function Documentation Progress

How to Patch the WordPress Core

This document will combine several external sources into one long informative document. Some of the contents will describe how to create a patch, how to create a Trac ticket, and finally what can be done to move the process along to get the patch into the core of WordPress.

Disclaimer: Some of the contents in this article are from the codex, since this blog is GPL also, no violations were made. Other contents are inspired by external sources, which are not GPL, but none of non-GPL contents were used to prevent plagiarism and so that GPL license could be applied to all of the contents in this article.

The Process

The process to get a patch into the core can be a long one. However, you do have to complete some steps and stay on top of the patch to ensure several objectives before it can be committed. Be aware however, that without a Trac ticket, there is no hope for your patch ever getting into the core. If the commit team does not know of your patch and does not have access to your patch and purpose, then they won’t apply it. Be sure to create a Trac ticket and upload the patch file. The WP-Hackers list is not for posting patches to, even if it is likely that a helpful person will probably create the ticket and add the patch for you.

Lets say you are using WordPress and something that you didn’t expect happens. You then check the forums and try to get help there first. After confirming that the issue is a bug in WordPress, you can decide two things. You can either file a Trac ticket, and after you can choose to provide a patch which fixes the issue. The last part is optional, but it would move the issue ahead of the queue to be in the next release if there is a patch for the ticket.

For the sake of this article, lets say you decide to provide a patch along with the ticket. The following can also apply, if you decide to provide a patch for an existing ticket with no patch.

  1. Checkout WordPress Trunk Repository.
  2. Make changes to the core.
  3. Save the changes to a file, in the form of a diff.
  4. Create the ticket (if it doesn’t exist already) and fill in the details.
  5. Upload the patch
  6. Stick around to keep on track of any comments, suggestions, and to keep the commit team interested.

Now that the process is available, lets go step by step through the each process in more detail.

1. Checkout the WordPress Repository

“Checkout” is a term to describe the process of downloading the contents of a repository. In this case, it is the WordPress repository and the “trunk” folder. In Windows, this is a very easy process, made possible by TortoiseSVN. Windows does not come with Subversion, like most Linux distributions do, so you will need to install TortoiseSVN manually.

You can download TortoiseSVN from the web site and after you download it. Click on the installation to install it. After you install it, it will ask you to restart. After you have restarted, you can begin using the functionality.

How TortoiseSVN works, is it adds a context menu to the right click. So if you right click on a folder, it will have new options. One of these options is “SVN Checkout”, but you should only do that in an empty folder that you created.

  1. Create a new folder, call it “WordPress”
  2. Right click on the folder name or if in the folder view, then right click in the window.
  3. In the menu, click on “SVN Checkout”
  4. When the box comes up, type in “http://svn.automattic.com/wordpress/trunk”

That now describes the process of checking out the WordPress repository in Windows, using TortoiseSVN.

The WordPress.org has a section for downloading WordPress using Subversion. That page also describes how to create patches for WordPress using the command line.

2. Making Changes to the Core

You can use any editor to change the files in the repository. Subversion does not have or need any special editor, so you can use your favorite or Notepad.

When you make changes to the files in that folder that you used to checkout the WordPress repository, they will show up differently (on Windows). On Linux, you can use the command “svn status” to find which files you changed.

Unless you are a member with commit access, which is only a handful of people, you will not be able to commit the changes. Therefore, it will be futile to try to click on “SVN Commit” on Windows or type “svn commit” on Linux command line.

3. Creating a Patch File

Creating a patch file on Windows involves has two options. Either creating a patch for a single file, or creating a patch which includes more than one file. The steps are similar for both, but there are several differences when creating a patch for a few files.

  1. Single File

    1. Right clicking on a file.
    2. Hover over the “TortoiseSVN” menu text
    3. Click on “Create patch”
    4. Click “Ok” because there will only be one file and that is the file you right clicked on.
    5. Save the file using the file extension of either “.diff” or “.patch”
  2. Multiple Files

    1. Right click on the folder area, not on a file, in the folder where wp-settings is located.
    2. Hover over the “TortoiseSVN” menu text
    3. Click on “Create patch”
    4. Choose the changed files you want to be part of the patch.
    5. Click “Ok”
    6. Save the file using the file extension of either “.diff” or “.patch”

When saving patch files, save them with the file extension of either “.diff” or “.patch”, so that Trac and display the DIFF on the site. It helps with the ability to review the changes and it is difficult to read diff files to understand the context of the changes if you don’t.

4. Create a Trac Ticket

  1. Go to WordPress Trac site
  2. Log in or create a new account and then log in.
  3. Click on “New Ticket”
  4. Fill in a descriptive title which summarizes the defect or feature and will provide interest in the ticket.

    The title is what the community sees and how the figure out if the ticket is worth checking or not. If a bad or non-descriptive title is given, then it might be passed over as being uninteresting and hinder someone who might otherwise be interested from providing a patch sooner.

  5. Fill in as much details about the ticket defect or feature request as possible.

    The more details, the more chances of someone providing a patch that fixes the defect or can create a patch for a feature request. For defects, have as much system information as needed (no passwords) and for features, describe the purpose as well as the feature details. The more details, the better off and the sooner the ticket might have a resolution.

  6. Choose the correct component, version (if defect), and do not set the milestone (unless you are going to immediately provide the patch).

5. Uploading the Patch

In the Trac ticket page, click on “Attach File” and upload the patch. After adding the patch, add “has-patch” to the keyword field and save the keyword.

6. Keeping on Top of the Patch

Your patch will not get into the core of WordPress until someone with commit access adds it. This can take anywhere from a couple of hours to a few weeks to a few months or in the worse case, never. It can be disheartening to create a patch, spending all of that time and then never have your patch committed. There are several reasons for this, so don’t get mad yet.

  1. Commit team might have higher priorities to complete first.

    The commit team has several priorities and areas they are interested in first. They should also be given enough time to review the patch, review the ticket, and whether the severity warrants the resolution of the defect or feature. It might be that a member of the commit team is taking the time to clean up the patch code, so that it is up to WordPress standards.

  2. Defect or feature does not provide enough rationale or interest from the commit team.

    There have been several times, when developers just aren’t interested or know enough of the problem to realize whether the patch provides the best solution. If that is the case, then provide explanations and rationale for why the patch should be committed. Keep on top of the issue, whether it is a defect or feature, because sometimes the commit team forgets that there is a patch and what the issue is. They might have been wanting to commit the patch, but it left their minds as other issues more important were bought up before they could.

  3. Clearly define, explain and demonstrate your problem or feature request.

    The more details the commit team has on the defect or feature, the better they can decide whether the patch (if any) is worthy of inclusion in the core or some extraneous problem that can be solved using a plugin. Do not be mad, if the commit or community members state that the solution could be better solved using a plugin. Also provide further rationale and explanations that might be needed to provide reasoning to why the patch should be included.

    If the solution adds extra configuration options, then you can pretty much count on your patch never being committed. The WordPress commit team does not like patches and solutions which add extra options. Any patch would need to make due without them. A solution would to use apply_filters() to pull in options, that would allow for plugins to be made instead of adding additional options to in the administration.

  4. Carefully consider, and take into account advice and feedback given on trac.

    Be aware, that if your patch is not committed in a reasonable amount of time for a defect, that it might be that you didn’t provide the best solution for the problem. If that is the case, then take in account the suggestions made by the community and commit team alike. If you disagree with the community members, then explain why your method is better and debate the issue. The WordPress community wants to have the best and better solution in the core, and not something they don’t agree with. Debating the point might also provide the rationale for the commit team to bring your patch into the core.

    There are quite a few veterans in the WordPress community that have some pull (karma, if you will), so their opinion/reasoning might trump yours. Use the recommendation that every suggestion should be considered, no matter who the person is that is making the suggestion. The goal is to have the best solution, so work with the community and commit team, so that the best solution can be bought into the core.

  5. Write easily understandable, documented code.

    The requirement standards for new functions inclusion into the core has been increased. New functions MUST be documented using the Inline Documentation standards. Not having that documentation may hinder the inclusion depending on the severity of the defect. For features, document the code, even if you are unsure that it will be included into the core. That way, the patch won’t be rejected, even if the commit member wants to include it.

    Follow the WordPress coding standards as much as possible to get the code included in to the core. You might want to profile the code to make sure that it doesn’t create any unwarranted bottlenecks in the code. Simple is better, try not to create complex code where simplified code would work. It is difficult to give an example, but most people will know it when they see it.

  6. Consider writing a plugin instead.

    There are moments, when the only way to prove whether or not a feature request should be added to the core, is by proving that enough people want to have the feature. If it is possible to make a plugin, then the suggestion will be that you make one. If enough people use the plugin, then you can come back with the proof to have the feature added. If the feature is not possible without modification of core files, then create a patch which allows for your plugin to work that implements the rest of the functionality.

  7. Appropriate tags in Trac help attract attention.

    After you add a patch, add the keyword “has-patch” in the keyword field of the Trac ticket. This will tell developers and the WordPress community that the ticket is ready to be reviewed for possible inclusion into the core.

    If enough time has past and you are wanting to know why the patch still hasn’t been committed, then add “dev-feedback” to the keyword field (remember, commas are not used to separate keywords, spaces are).

References

  1. “How does code make it into WordPress.” WordPress codex.
About these ads

January 21, 2008 - Posted by | Quality Assurance Series | , ,

2 Comments »

  1. [...] Jacob Santos explained “unit testing” in his Testing with WordPress. Interested in learning how to patch the WordPRess Core? [...]

    Pingback by Ryan Joy (atxryan) / WordCamp Dallas 2008 - Day Two | March 30, 2008 | Reply

  2. [...] I stated earlier that I had mix feelings when writing the How to Patch the WordPress Core, it is because I had to almost beg to get patches that I know fixed issues committed to the core. [...]

    Pingback by Jacob Santos » Blog Archive » Response to Mark Jaquith’s Answer | April 27, 2008 | Reply


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: