Trac is an open source project that serves as a bug tracker and project management tool for WordPress. Using Trac, developers can browse source code history as well as manage bug reports and feature development.
Tickets are used for both bug reports and feature development, and may be created by anyone with a WordPress.org account.
Ticket Properties #
Tickets are assigned numerous properties that provide a snapshot of the status of the ticket.
Title and Description: Provide a strong title and clear description. For the title, it is generally best to describe the problem, not a solution. Concentrating on the problem, rather than the solution, is a good mantra in general. For the description, it is generally best to include steps to reproduce, and actual versus expected results (for bugs), and proper rationale (for enhancements).
Type: A ticket falls under one of four types: defect (bug), enhancement, feature request, and task (blessed).
- Defect (bug): A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.
- Enhancements: These are simple improvements to WordPress, such as the addition of a hook or an improvement to an existing feature.
- Feature requests: These are proposals for new features. Feature proposals should generally begin the process in the ideas forum, on a mailing list, as a plugin, or brought to the attention of the core team, such as through scope meetings held for each major release. Unsolicited tickets of this variety are typically, therefore, discouraged.
- Tasks (blessed): Feature development for the upcoming major release centers around task tickets, which are major features or important enhancements that have been blessed by the core team. A ticket should otherwise never receive this designation.
Milestone: The milestone is the WordPress release where that ticket is expected to be resolved, such as 3.7. By default, all tickets are assigned, upon creation, to the Awaiting Review milestone to prevent scope creep. Only committers or trusted core contributors have the ability to change milestones.
Keywords: After the milestone, the keywords field is the most important field. These are not like tags on a WordPress post, but rather a defined list of keywords that describe the ticket’s current status in our development workflow. We use these keywords to build important reports. As an example, tickets tagged with ui-feedback or ux-feedback are pulled into a report on which the UI team heavily relies. See Trac Workflow Keywords for a complete list of the keywords.
Component: The component is the area of WordPress that the ticket affects. The UI team, for example, will often be working on tickets in the Graphic Design, UI, or Accessibility categories. Try to choose specific components (when applicable) over more generalized ones, such as General or Administration. Components are used in reports to provide a logical grouping of tickets by subject area.
Tickets for core plugins, such as the importers, are managed under the Plugins or Import components, and current and former default themes are managed under the Bundled Theme component.
Issues with the WordPress.org site were formerly managed on the same Trac as WordPress core. As of June 2013, meta.trac.wordpress.org is now the proper, canonical place for bug reports to be filed that are related to the WordPress.org site. See the full components list to determine if your issue should be reported there.
Resolution: Upon one or more commits to the codebase, a ticket may be closed as fixed. Not all tickets result in a commit, however, and may be closed for other reasons:
- duplicate: The ticket is a duplicate of an existing ticket, which will be referenced by the contributor closing the ticket.
- invalid: The ticket is not a bug, or is a support request.
- worksforme: The bug reported in the ticket cannot be reproduced. Sometimes, an existing plugin, hook, or feature may render the ticket moot, so the ticket can be closed without further action.
- wontfix: The ticket will not be addressed. Occasionally, bugs are considered to be acceptable edge cases, and will not be addressed further. This is sometimes used when a request for an enhancement or feature has been rejected for core inclusion.
- maybelater: Similar to wontfix, maybelater is used for a ticket that, while perhaps not outright rejected, has no current traction.
There is certainly some overlap among these five resolutions. It is not an exact science.
Severity and Priority: The severity is the seriousness of the ticket in the eyes of the reporter. The priority is the seriousness of the ticket in the eyes of the project. Generally, severity is a judgment of how bad a bug is, while priority is its relationship to other bugs. Only committers and trusted core contributors have the ability to modify the priority.
Version: The version of WordPress being used. Ideally, this would be the earliest affected or applicable version. It should not be updated to a later version once set, as we utilize this to track the age of tickets and bugs, regressions, and the like.
Individuals have three roles on Trac tickets:
Reporter: The person who opened the ticket.
Owner: This field is typically left blank, even if you have contributed a patch. The owner component is used by committers and trusted core contributors to accept and assign tickets among themselves. Committers utilize the field to offer traction for a ticket, to identify they are investigating, committing, or otherwise following a ticket, or to tentatively accept the bug or enhancement for core inclusion. It is also common during the feature development phase for developers to accept tasks in the area of responsibility for which they have volunteered, as well as related bug reports. Trusted contributors may assign tickets to others based on an inside knowledge of who should be responsible for reviewing it.
CC: As long as your email address is configured in Trac preferences, you’ll receive email updates for any tickets you’ve created or ones you’ve commented on. The field is generally a visual confirmation you are adding yourself to the ticket and wish to receive updates. From time to time, it may make sense to add other individuals to the CC field, such as when a committer requests this. It should be noted that most committers and core developers read every ticket and comment anyway.
Triaging and Punting #
New tickets are automatically assigned to the Awaiting Review milestone. Upon initial review, it may be recommended for closure, or require more feedback from the reporter or a core developer. Keywords often used here are 2nd-opinion, close, reporter-feedback, and dev-feedback.
It may also be moved to a milestone by a committer or trusted core contributor:
- The next point release milestone (for example, 3.6.2 if the current release is 3.6.1) is for critical bugs and regressions. Our point releases are only for security fixes, critical bugs, and regressions in behavior from the previous version of WordPress. We do not fix regular bugs or enhancements in these releases.
- The next major release milestone (for example, 3.7 if the current release is 3.6.1) is for tasks and features slated for the release, bugs affecting those features, and regressions in the current alpha or beta version over the latest release. Existing bugs may also be addressed, but this generally won’t be considered until a solution exists, unless the bug is sufficiently major to warrant priority. Enhancements may also be included at the discretion of committers, but only during alpha development (prior to the beta release). Larger enhancements are generally not considered for the next major release as they are out of scope.
- The Future Release milestone is reserved for other tickets. It’s been determined as a potentially good enhancement or confirmed as a bug, but it is not slated for the next release of WordPress.
Punting Tickets #
Tickets are punted when they are moved out of a minor or major release milestone to a future milestone. This generally happens at different intervals in the cycle to lower priority tickets. Some tickets are individually deemed as too complex or out of scope, and are therefore moved.