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.

January 21, 2008 Posted by | Quality Assurance Series | , , | 2 Comments

The Automated Testing Methods

There are quite a few testing techniques and ways to implement test cases for an automated test system. A few that should be implemented for WordPress are listed, but there are others and with better details on other web sites. I’m not the authority on unit testing and I don’t pretend to be. However, what I do know is detailed below and take my word with a grain of salt. I will say that the details are in general what can be applied when coding test cases.

  1. Unit Testing

    Unit testing is quite what it says, you are testing a single unit or component of the library. This can be function or method. This method usually makes use of mock objects for classes to correctly test the behavior of an individual unit.

    This method has the advantage of allowing for testing code coverage and finding out just how accurate your tests are.

  2. Regression Testing

    I would argue that this is the easiest of the methods, since all you are doing is checking the current behavior and writing tests to make sure that the current behavior continues in later versions.

    You’re not actually getting down into the source code and making sure that all of the branches are covered and that the correct results are covered. You are also not always checking that incorrect data has a fallback in place to prevent failures.

  3. Functional Testing

    Functional Testing is a step up from unit testing, where you are testing a component within the software environment. This is more how the Automattic Automated Testing suite is set up. It does not allow you to test the code coverage, because since the entire software environment is running it will skew the code coverage results.

    The primary difference between unit testing and functional testing is that with unit testing, every test in unit testing is self contained and does not interfere with the other tests. With functional tests, you have to be careful, because the tests are not contained and will affect other areas. Other than that, it would be easy to switch from unit testing to functional testing and back again.

  4. Acceptance Testing

    Users do this already, but this method is more about automating the process of what users do. It doesn’t completely replace user testing, but it does complement it. It reduces the tedious tasks of inserting content and does that and returns the results. For known problems, it is very useful in order to prevent presentational regressions.

    It is also quite frankly, in my humble opinion, one of the most difficult to accomplish for browser based acceptance testing. Selenium is very helpful, but setting that up has been difficult for me. If you can get it set up then PHPUnit can talk to it and it would be as easy as writing any unit or functional test.

January 19, 2008 Posted by | Quality Assurance Series | , , , , | 2 Comments

What is Quality Assurance?

Quality Assurance is ensuring the quality of a product. It is an ongoing process that never ends, or at least not during the life of the product. Quality Assurance in open source is a more open process and anyone can help.

It involves testing, documentation, and automated testing. Testing is the most important factor, but documentation is equally important. Actually, Software Quality Assurance is a paradigm that involves a great deal more, but for the purpose of this discussion, I’m going to limit this to just the above three.

What it means to the User

When you commit to Software Quality Assurance, you are telling the customer and user that you have a policy in place that will hopefully prevent a majority of preventable bugs from occurring before the product is released. In the likely event that a bug is found, there is a policy in place that ensures that it will be fixed and prevented (in most cases) from occurring again in the future.

It also says that there is detailed documentation for both the users and developers which extensively covers the topics that both groups will want to know. Extensively covers the known areas and areas that have been questioned about in previous versions. Covers the more difficult areas better and with more details than “simpler” topics that users and developers should not have any problems with.

Solving Issues

Users, testers, and developers all help with the process. The user can make a request for a new feature that will improve the product or report a problem in the product. The testers will usually beta test and test versions of the product before it is released reporting any issues that come up. Developers will take the reports and create patches that fix the issues for the next version.

Developers will also write test cases that check whether the problem is fixed and if the problem reoccurs in a later version. If the problem does reoccur then the problem is immediately known and can be rechecked until the regression is corrected. If the regression was intentional, then documentation would have to be updated and other developers updated on the change.

Writing Documentation

Writing documentation should be concise, tutorial type explanations in language that an user and/or a developer will understand. For open source, I would just recommend writing something as close as possible to this style as you can get and cut the extraneous details (ex, I don’t want to know about how you used it in your project and the history, unless it further explains the purpose of the function, sometimes it is useful, other times it is not).

Not everyone is a professional writer (myself included), but there are enough people who are that if you give them enough information, they can edit it to where it is better. I write with the assumption that someone is going to look at what I wrote and point out mistakes and hopefully, instead of cussing me, will actually move to fix the mistakes. On Wikis, this is very simple process, on this post however, they would have to send it to be me personally or export it to their blog or wiki.

Testing Software

You are testing that the software works (well, yes you are for those who are disagreeable), you are trying to test whether the software breaks. Therefore it makes more sense to input invalid data to see if what is expected happens or not. Developers (indeterminate amount, I have this problem, so I only speak of myself and the general stereotype of developers with testing their software) have a habit of only using valid data.

You only know that the software works if you enter something invalid and it didn’t break on that input. If it breaks on invalid input, then there should be a check in place that either automatically the problem or informs the user of their mistake. There is also automated testing, which automates the lower level testing and higher level testing which automates some of what users do.

January 18, 2008 Posted by | Quality Assurance Series | , , | Leave a comment

Getting Involved with Quality Assurance

WordPress is a community effort and it takes everyone in the community to make WordPress the best it needs to be. Getting involved is as easy as using WordPress and reporting when defects show up. It can get up to creating patches for WordPress Trac defects or enhancements. Everyone can do something and people are doing great things for WordPress every day.

Testing WordPress Trunk

If you use just the versions of WordPress that are released, some bugs that you find could have already been fixed on trunk and just awaiting the next release. If you want to really test WordPress, you must first check out the Trunk and join the WP-Testers mailing list.

When testing make sure you input both invalid and valid information and keep in mind what you are expecting what the actual result is. You are trying to break WordPress! If something doesn’t break, then you aren’t trying hard enough or WordPress already has checks which prevent it from breaking.

Reporting Bugs

Reporting bugs is one of the easiest ways to get involved with quality assurance. If a defect is not reported then the WordPress developers and community will not know of the defect. The sooner a defect is reported and confirmed the sooner it can be fixed.

You can report bugs at the WordPress Trac Site. You can also find more information on reporting bugs at the WordPress Codex: Reporting Bugs. As an reminder, you may need to stay around for the life of the ticket to make sure to answer any questions and to follow up on anything that developers or others may need to satisfy the requirements of the report.

Remember: make sure to check the defect or enhancement hasn’t already been fixed or reported. Doing so, will be appreciated by those who have to mark your ticket a duplicate.

Writing Patches

The next step from reporting defects or offering suggestions for enhancements is to provide solutions to existing defects and enhancements. As for most people, you may choose whatever ticket of your ability and liking. You don’t have to start at the top and work your way down.

It should be noted that the tickets of low priority probably won’t be as committed as quickly as those tickets that have a higher priority. Give enough time for the core development team to look over your ticket and see if it worth committing. Keep in touch after you commit the patch to make sure that answer any questions those in the community and core development team may have.

If a reasonable amount of time has past without any resolution with an existing patch, writing another comment asking for a response or set one of the keywords to include ‘dev-feedback’ (without the quotes). It might be that the development team might have forgotten about your ticket. Leaving a friendly reminder might push the ticket ahead in their minds.

When your patch does get committed, rejoice, it will be one less ticket in the queue. Any amount of help is appreciated.

Writing Codex Documentation

The codex is the central place for finding information and help on WordPress. As many features and solutions that WordPress offers, the amount of help is far to broad to be completely covered by any one page or person. If you notice that there is a section that is missing, then sign up and add it.

Writing Inline Documentation

WordPress also needs to have inline or source documentation for those who browse the source for their information. Not everything can be learned from the codex and since the codex can grow outdated, it would be useful to look at the source from time to time. Those that do look at the source need additional information in order to quickly realize what the code is supposed to be doing.

It is also useful for those who can’t read code as clearly as some of those who have been reading and writing code for a long time. In order words, it helps novices of PHP to learn what WordPress is doing. They might not be able to build an application like WordPress, but they can write plugins that are useful for them and/or other people.

There is currently an Inline Documentation Standard that should be used. It is unwise to write a lot for functions since there is a tiny amount of overhead in processing the comments. Not much, but leaving as much detail to only describe what the function does should be enough. Any examples can be located at the codex.

Writing Test Cases

There is currently an Automated Testing Suite for WordPress which you can provide test cases for. Test cases are useful to prove or disprove a defect and whether a patch fixes the defect. Without test cases it would be difficult without manual testing to find out if the defect was fixed. The test cases also can test whether the defect shows up in the future (called a regression).

Writing test cases will be detailed in a later post. Make sure to stay around to learn more!

January 14, 2008 Posted by | Quality Assurance Series | , , , , , , | Leave a comment