Every application has bugs -- as long as humans write code, there will continue to be errors in software. Some errors are trivial, while others are critical. Open-source projects like WordPress need the participation of their user communities to identify bugs in their software, as well as to plan for new features.
All types of feedback — whether they're genuine bugs or feature requests — are reported the same way in the WordPress project. Read on to learn how to report bugs and issues for WordPress... you may also want to read Contributing to WordPress to find out how to contribute to the documentation and other areas of the WordPress project.
Reporting security issues
While we try to be proactive in preventing security problems, we do not assume they'll never come up. If you believe you've found a security problem in a release of WordPress please see the Security FAQ for information on how to report the problem.
It is standard practice to notify the vendor (the WordPress developers, in this case) of a security problem before publicizing so a fix can be prepared and public damage due to the vulnerability minimized.
Reporting Bugs in Plugins and Themes
If you find a bug in a Plugin or Theme you are using with WordPress, do NOT report it using the procedures in this article! Instructions in this article apply only to bugs in the WordPress core, and do not apply to bugs in plugins and themes.
For plugins which do not reside in the official repository, and for themes, check the documentation that came with the plugin or theme for instructions on where to report bugs. If no bug reporting information came with your plugin or theme, you'll need to contact the author directly.
Overview of Bug Reporting and Resolution
There are several steps in the process of reporting and resolving a WordPress bug. Here is an overview; more details are in sections below.
- A user finds a bug that appears to be in the core of WordPress (not in a Theme or Plugin).
- The user tries to make sure it is actually a bug. See Before You Report a Bug (below).
- If it is determined to be a bug, the user submits the bug report, called a ticket, to Trac, the WordPress bug tracking system. See Reporting a Bug (below).
- A WordPress developer (who could be a volunteer like you) confirms that the bug does actually exist, and that it should be fixed, and marks it as such in the ticket. See Trac Keywords list (below) and Bug Resolutions (below).
- A WordPress developer (which could be you) decides to fix the bug. The developer may choose to take responsibility for the bug by clicking on the Accept ticket option near the bottom of the ticket, though this is not required. Then the developer figures out how to fix the bug, creates one or more patch files, and uploads them to Trac. See Patching Bugs (below). Also, if you want to help with fixing bugs, but don't know what bugs to fix, see Finding Bugs to Fix (below).
- Members of the WordPress development group (including volunteers) test the patch, to see if it fixes the bug and doesn't break anything else. They add comments and keywords to the ticket to indicate their results. See Trac Keywords list (below).
- One of the WordPress developers with authority to modify the official WordPress source code commits the patch to the core code in the SVN repository. They are more likely to do this if the bug and patch has been verified by someone they trust.
- Finally, the person who commits the patch sets the bug ticket status to closed and the resolution to fixed. See Bug Resolutions (below).
Details of Bug Reporting and Resolution
The sections below add details to some of the steps outlined above.
Before You Report a Bug
With large projects like WordPress, so many users report bugs that there's a good chance your bug has already been reported. Because of this, it's very important to check to be sure it's not already in the system before you submit it. If you are new to reporting bugs in WordPress, it is also a good idea to discuss the issue with more experienced developers before reporting it. Please follow the steps below.
- Make sure the bug is actually caused by WP Core code
- Just because an error message points to a core file, doesn't mean that's where the problem is.
- Here is a debugging file that you can place in your wp-content/mu-plugins folder (create it if it doesn't exist) to see where the error is coming from.
- Search for your bug or feature request in Trac by using Search or a Query.
- If your issue has already been reported, please do not report a duplicate bug. If you have further information to contribute, log in and add a note to the existing bug.
- If your issue is similar, but not quite the same as another issue, you may decide whether to add a note to the similar issue, or report a new one. It can be difficult to decide whether your issue warrants a new submission, but in general if you just have more information to contribute to a current, open issue, simply add a note to that issue. If you have a different enough issue, or if you are experiencing a recurrence of an issue that was previously resolved, report a new bug.
- If your issue was recently reported and then closed, and you do not agree with the resolution, you can also reopen the ticket and add a comment as to your reasoning.
- It is best not to re-open bugs that have been closed for some time (E.G. On a milestone relating to a version more than 1 release old) - in that event consider a new ticket.
- Please do not change the version number on bugs that have been reported already. The version number relates to the version in which the bug was originally discovered. If you're seeing the same bug in a newer version, mention so in a comment.
- To discuss a bug before reporting it in Trac (e.g. to figure out if it is really a bug in the core of WordPress and not in a plugin or theme), you can post a question on the WordPress Support Forum, discuss your issue on the #wordpress IRC channel, or have an email discussion on the Testers or Hackers mailing list.
Reporting a Bug
Trac is the name of the official WordPress bug tracker. It uses the open source bug tracking software Trac which is a product from Edgewall Software. Follow these steps to create a good bug report in Trac:
- Read Before You Report a Bug (above), and verify that you have a new bug that is appropriate to report.
- Read this article on How to Report Bugs Effectively, and the Trac Ticket documentation.
- Log into WordPress Trac using your support forum username and password. If you don't have an account at the support forums, register so that you can login to Trac. This is essential for communication about your bug, since the developers may need more information (and you cannot create a ticket without logging in).
- Click New Ticket in Trac to reach the bug reporting page.
- Fill in the [#Ticket_Fields].
- Click Submit Ticket (after previewing it).
Finding Bugs to Fix
If you want to fix bugs in the core parts of WordPress, but don't know which ones to fix, here are some suggestions on how to find bugs to fix:
- Look through the Needs Patch Report on Trac (which lists bugs that have not been marked with the "has_patch" keyword), the Lacks Attachment Report on Trac (which lists bugs that do not have a patch file attached), or other Trac reports for bugs that look interesting.
- Send an email message to the wp-hackers mailing list and ask how you can help.
- There is also sometimes bug triage on the #wordpress-dev IRC channel
- Occasionally there are bug days on #wordpress-dev. You can read about what happens in a bug day in WordPress Bug Hunts, and subscribe to either the wp-hackers or wp-testers mailing list to find out when they happen.
- Consider joining the wp-trac email list to follow the discussions about each Trac Ticket.
- Read Finding Bugs to Fix (above), and find a bug to fix in Trac.
- Connect to the WordPress Subversion (SVN) Repository using the username and password you acquired when registering. Read Using Subversion if you are unfamiliar with SVN.
- Figure out how to fix the bug, by modifying WordPress core files. You may want to discuss your proposed solution on the wp-hackers mailing list before finalizing it.
- Test your fix, verifying that the bug has been fixed, and that nothing else in WordPress is broken in the process.
- Create a patch file (or files) containing your fix. This is basically a diff of the fixed file(s) and the originals from SVN. See How to Patch WordPress by Owen Winkler for detailed instructions. There are also instructions for Linux/Mac command-line users in Mark Jaquith's Toolbox and Windows Tortoise SVN users in Westi's Blog.
- Upload it to the ticket using the Trac Attach file button, and add has-patch to the keywords. Please don't overwrite any existing (previous) patches. If the patch needs testing, you might also put needs-testing, or one of the other Trac keywords; see Trac Keywords (below) for more information.
Patch Writing Guidelines
All patches should:
- be made against the latest code in the SVN repository.
- be made against the root WordPress directory and not against a subfolder.
- adhere to the coding standards.
- Short Summary
- Make the summary short but informative and accurate, as this is the ticket title that will be displayed in search results.
- Full Description
- Fill in a full description of your bug or feature request. Include a description of the problem, steps someone else would have to take to reproduce the problem, maybe an example of the bug in action (i.e. a URL), and a description of why it is a problem worthy of being corrected. Also include information about your platform, such as operating system, web server software, PHP version, MySQL version, and WordPress version. The better your description, the better the chances of having the bug resolved promptly.
- Ticket Properties
- This is how urgent the bug is. The core developers will usually rank the bug's priority, so this option may be read-only.
- Select the component of WordPress where the bug was found
- The significance of the issue. Select a severity based on how critical you consider the issue to be. If in doubt, leave this option as Normal.
- Assign to
- If you know of the developer who is responsible for the code that the bug is in, place their Trac username here. You can also take responsibility for the bug yourself, by putting your own Trac user name here. This is optional and could speed up developer attention to the bug.
- By what version this issue should be resolved, at the latest. The developers generally set this, so this option may be read only.
- The earliest version of WordPress where the bug was found or the current stable version for enhancements and feature requests. (Do not change the version on pre-existing tickets.)
- There are some standard keywords used to flag your bug's status (see Trac Keywords below).
- Who bug information and updates should be sent to. If you want to be kept informed, enter your own Trac user name here. You will then be notified by email any time a change is made to this report, or a note to the bug is added. Don't ignore these emails; any time a change is made, be sure to check the report for updates. Developers may need further information from you, and this is their only way of getting in contact with you. Note: you need to go to the Trac Settings page to set your email address. Putting it into your Support Forum profile will not get it into Trac for purposes of CC messages. Note: If you are the bug's reporter, you will already get messages (if your email is known), so no need for CC.
- expected behaviour isn't happening
- current behaviour is improved or modified
- completely new behaviour is added
There are a number of keywords with defined meaning used in Trac that are commonly used; some are also searched for by Trac Reports. Keywords should not be thought of as generic 'tags,' which are not necessary.
- A response is needed from the reporter. Further investigation is unlikely without a response to the questions from someone experiencing the problem.
- A response is wanted from a core developer or trusted members of the development community.
- ux-feedback and ui-feedback
- A response is needed from the core team with regards to the desired user experience or interface.
- Feedback is needed with regards to RTL support or a patch for RTL support is needed.
- Another person is needed to express an opinion about the problem or the solution.
- A proposed solution to the ticket has been attached, and it is ready for review.
- The ticket has been reviewed, found to be desirable to solve, and marked as especially needing a patch, or the submitted patch doesn't work and needs to be redone.
- The ticket requires changing the visual appearance of one or more elements.
- A submitted patch no longer applies cleanly to the WordPress core files, usually because nearby code has been modified since the patch was submitted. The patch needs to be merged and re-submitted.
- One or more people are needed to test the solution. When testing a patch, please comment with the patch filename that was tested, how the patch was tested, and which version of WordPress was used (including the SVN revision number, if it is not an officially released version).
- The ticket has been reviewed, found to be desirable to solve and we would like some unit tests written to test the functionality and any patch that may exist before committing a change as the risk of causing other issues is high.
- Inline documentation for the code is needed. These are either place holder tickets for individual files or tickets with patches for new functions which need documenting before they are committed. A ticket created specifically for inline documentation should be added to the Inline Docs component instead.
- Documentation in codex needs updating or expanding. Remove the keyword from the ticket once the codex is updated.
- The patch has been reviewed and tested by a trusted member of the development community; therefore the patch should be considered a commit candidate and is ready to be added to the WordPress core files.
- This keyword should only be applied by committers. The keyword signals that the ticket is a priority and should be handled early in the next release cycle.
- Only used late in the development cycle (after string freeze) to track potential string changes, as translators need to be notified.
- The ticket is a candidate for closure with a disposition other than fixed (i.e. wontfix, worksforme, invalid, or duplicate). Often seen with reporter-feedback or 2nd-opinion, otherwise the ticket would have been closed in lieu of the close keyword.
A ticket in Trac starts its life in the open status, and (hopefully) is eventually closed. When a ticket is closed, it is marked with one of the following status designations:
- If your bug has already been reported in another ticket. If the bug has already been fixed in the latest development branch (which is probably not what you're running unless you have a local test blog), it will likely be closed as a duplicate of the original ticket.
- If it is decided that your bug isn't in fact a bug, but is the intended behaviour.
- If no one else can replicate the symptoms you describe.
- If your bug is a feature request that the developers don't want in the core.
- If your bug is a feature request that the developers don't plan on adding in the core, but might reconsider in the future.
- If the bug is fixed in the core subversion repository.
- The processing of your bug may require your participation. Please be willing and prepared to aid the developers in resolving the issue.
- Thank you for contributing to the development of WordPress!
- lead developer: one of the commiters that have the final word on important technical decisions. See Development Team.
- core commiter: a developer that has permanent commit access
- guest commiter: a developer granted commit access temporarily, usually for a specific feature
- core contributor: a person actively involved in Core development, but without commit access