How to use Trac

The WordPress project uses the Trac ticket tracking software to manage all tickets related to WordPress Core. However, Trac presents a lot of information, and is often overwhelming for new and experienced contributors alike.

This video will teach you everything you need to know about creating, updating, and browsing tickets so that you can effectively contribute to WordPress using Trac.

Helpful resources

Learning outcomes

How to create a new ticket.
How to update existing tickets.
Understand what the various ticket information fields mean.

Comprehension questions

What are the difference between components and focuses?
What does the version field represent?
What is the milestone field used for?

Length20 mins
TopicWordPress
LanguageEnglish

Transcript

0:01
Hi, my name is Jonathan Desrosiers. I am a WordPress core committer and the team lead of the WordPress core triage team. In this video, I’m going to cover how to use Trac.

0:13
If you’re not familiar, Trac is the ticket tracking software that the WordPress project uses to make changes to the code base. Every change made to WordPress is always accompanied by a ticket and Trac. To use Trac, you will require a wordpress.org account. Once you have one, you can log into Trac using the same credentials. After watching this video, you will have all the information you need to open a new ticket or to contribute to WordPress by helping to manage existing ones. Before we get started, it’s very important to know that security vulnerabilities should never be posted publicly, even when reporting the issue to the WordPress team. Please respect the project’s security policy by disclosing any vulnerabilities responsibly and privately to the project’s hacker one organization Trac is not the appropriate place to report security vulnerabilities. Okay, let’s get started. When you first open Trac, you’ll be presented with this screen. You may be tempted to ignore this page because there is a lot of text, but I recommend that you return here later and take a few minutes to read through it. There are many links to helpful resources that will help you better understand the different aspects of contributing to WordPress core. For now, let’s click on the Create a new ticket button and walk through the process of creating a new ticket in Trac. At the top of this page, you’ll see several bullet points providing tips to create a better more descriptive ticket. For example, you should always confirm that the issue you are reporting can be reproduced on the latest version of WordPress. There are also some specific types of tickets that should be reported to different locations. One example of this is a ticket that reports a bug or feature requests for the Block Editor. Those are better off being reported to the Gutenberg repository on GitHub. Since the changes must be made there before being merged into the WordPress core code base through Trac. Like the previous screen, I recommend that you return here later and take the time to read through these tips. Before creating a new ticket, it’s good practice to search for a pre existing ticket that identifies the same issue that you are reporting. It’s not uncommon for an issue to have been reported already by another contributor. Sometimes there are even patches that attempt to fix the issue for you to test. Doing this will help cut down the amount of ticket triage ng that other core contributors need to perform. To search for a pre existing ticket on track, use the search field at the top of the screen. We’ll talk a little bit more about using Trac search later on in this video. Let’s scroll down and look at the form and talk about what each field represents. The first field is the ticket summary. The summary is essentially the title or name of the ticket and will be displayed along with the ticket number in most places throughout track. Your ticket summary should clearly state the problem or feature. You’ll notice that as you enter your information into the form, the preview of the ticket is displayed. This is a helpful way to proofread and review your ticket before hitting Submit. Next is the ticket description. The ticket description is where you would enter all of your information about the bug that you are reporting or the enhancement that you are requesting. It’s important to be very detail oriented and provide as much information as possible. If you’re reporting a bug, please provide explicit steps that someone else can take to reproduce the issue reliably. The ticket description should not describe a proposed solution or implementation. The solution to the problem or the best way to implement an enhancement will change and evolve over time, as more contributors provide feedback. This helps to keep the ticket description the same over time while still remaining accurate. It also allows contributors to follow the progression of proposed changes in a chronological way within the tickets comments. For the purpose of this video, let’s assume that we’re reporting a bug. I’ve gone ahead and created a fake bug description already.

4:46
Moving down, you’ll notice that the next two fields are crossed out and disabled. These two fields can only be modified by community members with commit access, who are also known as committers, or trusted core contributors. includes but is not limited to official component maintainers bug gardeners or members of major and minor release teams. The first disabled field is milestone. The milestone represents the version of WordPress where the ticket is expected to be resolved. By default, the milestone is set to a waiting review. We’ll talk more about the different values for milestone a bit later on. The second disabled field is priority. priority is the seriousness of a bug report or ticket in the eyes of the project. Below that is severity. severity is the seriousness of the ticket in the eyes of the reporter. Generally, severity is a judgment of how bad a bug is, while priority is its relationship to other bugs. Please be reasonable when selecting the severity of a ticket. Just because the bug is affecting your site in a negative way, does not mean it is a blocker, critical or even major severity. and selecting the highest severity will not necessarily result in your ticket being fixed any faster. The overwhelming majority of tickets should fall into the normal severity. To the left is our next field ticket type. There are four types of tickets in Trac defects or bugs, enhancements, feature requests and tasks. You’ll notice that task is not an available ticket type feature development for the upcoming major releases center around task tickets, which are major features or important enhancements that have been blessed by a release squad or project lead. For this reason only the groups mentioned before are allowed to create task tickets. A bug is an error or unexpected result. performance improvements and code optimizations are considered enhancements and not defects. enhancements are simple improvements to WordPress, such as the addition of a hook or an improvement to an existing feature. Since we’re creating a bug here, I’m going to leave the type as defect. The next field is the version. The version represents the version of WordPress being used. Ideally, this should be set to the earliest affected or applicable version. If you’re able to test older versions of WordPress, working backwards to identify the first version of WordPress that experiences the issue you are reporting is very helpful. This could aid in identifying the exact code change that caused the problem. If you’re not able to selecting the version of WordPress that you are currently using is fine. However, if another contributor is able to work backwards and identify the first version of WordPress that experiences the issue, please do not change this version to a future version. trunk should only be used if the ticket addresses unreleased code in the WordPress developer repository. If you are using the beta tester plugin, it’s also possible that trunk applies to your bug. For the sake of this video, let’s say that this bug was introduced in WordPress 5.6, which was the last major release before recording this video. The next field is component. For the purposes of contributing, WordPress is organized into roughly 60 components representing well defined functional areas of core. This helps identify which areas of WordPress are affected by a specific ticket and groups those tickets together for contributors. Each component has its own ticket report on track is listed on the WordPress core components page. And links off to its own page where maintainers can add specific information about contributing to that component.

9:02
Further down, you’ll find a list of component maintainers. Each component has one or more maintainers. maintainers are responsible for triaging new tickets, looking after existing ones curating roadmaps, providing feedback to other contributors, and co working with other component maintainers. To help tickets be solved in versions of WordPress. Longtime maintainer is often have a very deep understanding of a components history and how their component impacts other areas of WordPress. on track, you’ll be able to identify component maintainers by this badge next to their name. This will appear whenever a contributor comments on a ticket that belongs to a component that they help maintain. You may also encounter a few other labels, such as this core committer label, or this lead developer label in general is a default component. It’s always better to select a more specific component over a more generalized one whenever possible. For this ticket, let’s select the media component. Below the component field you’ll find focuses focuses are broad concepts that help break tickets down by specialties and skills rather than functional areas of core. For example, accessibility is not a specific area of core. Instead, it’s something that should be considered throughout the entire user experience. A ticket about inline documentation should still receive the attention of contributors to a more specific area of core.

10:38
But anyone who focuses on inline documentation should still be able to provide feedback. For our example bug report, let’s assume that the inline documentation associated with the code producing the unexpected behavior is inaccurate. While our ticket belongs to the media component. Selecting this focus will potentially help inline documentation contributors discover the ticket so that they can provide any suggestions or guidance that they may have.

11:10
To the left that focuses you’ll find workflow keywords. Each keyword has a specifically defined meaning. All keywords belong to one of two groups, status based and action based. At the time of this recording, there are roughly 30 keywords that are officially recognized. I’m only going to cover a handful of keywords in this video. The full list of keywords can be found on the Trac workflow keywords page in the WordPress core handbook. I recommend reading through the list in full after watching this video. Let’s assume that our ticket would require changes to a core function, I’m going to add the needs unit test keyword. This indicates that any changes associated with this ticket should be accompanied by unit tests. Providing unit tests with a ticket will usually help a ticket progress more quickly. unit test can confirm the new desired behavior is being achieved while preserving all of the correct behaviors that currently exist. Let’s assume that I have a patch to attach to this ticket. I’m going to check the I have files to attach to this ticket checkbox so that I am prompted to upload my files after creating the ticket. I’m also going to add the has patch keyword. This indicates that a working patch proposing changes to address the problem or enhancement described in the ticket is attached. If you do not have a patch to attach to the ticket, you can add the needs patch keyword. It’s not uncommon for a patch to become stale throughout the lifecycle of a ticket. When a patch becomes stale, it will no longer apply to the current version of trunk automatically and will need to be refreshed so that other contributors can review and test the changes. When this happens, the needs refresh keywords should be added to the ticket so that contributors can identify which tickets need patches to be refreshed. When adding the needs refresh keyword, please leave the has patch keyword as the ticket does in fact have a patch. It has just become dated and needs some more attention. Sometimes refreshing a patch is very trivial. But other times the code changed in the patch was altered while addressing another ticket and will need to be recreated from scratch. Let’s also assume that I have screenshots to attach demonstrating the problem before and after the patch is applied. When this is the case that has screenshots keyword is appropriate. best effort should always be made to include before and after screenshots whenever modifications are made that result in visual changes. If you do not have screenshots to attach but feel that they would be useful to help document this problem. The needs screenshots keyword should be used. I’m also going to add the second opinion keyword. While I’m attaching a patch that fixes the issue. I’m not sure that the proposed solution is best and I would appreciate a second opinion from another contributor. If at any point you encounter a keyword that you’re not sure of the meaning just hover over the keyword, a tooltip will appear with a short description of what the keyword is meant for. Okay, I think our ticket is ready to go. Let’s scroll down and give it a proofread before clicking Create ticket.

14:48
Looks good.

14:49
Let’s go.

14:52
If you check the I have files to attach to this ticket checkbox. You’ll be presented with this screen after clicking Create ticket If you forgot to select the checkbox, it’s okay. You can easily get to the screen by viewing the ticket. When adding files to a ticket, it’s important to always upload them directly to track while pasting a link to the file in an external file storage service like cloud up or Dropbox. Maybe more convenient, those links almost always become dead links. Eventually, files added directly to Trac will always be preserved indefinitely, ensuring that contributors visiting ticket today, next week, next year, or even 10 years later, we’ll be able to access to files that provide the needed context to resolve the ticket. Keywords almost always need to be updated after adding attachments to a ticket. Make sure to return to the ticket screen and update the keywords appropriately after adding your attachments. That’s it. That’s all you need to know to open a ticket on track. Easy right. Now that you know how to create your own ticket, let’s take a look at how to browse through pre existing ones. Clicking the tickets link in the blue bar at the top of the screen will always bring up this overlay. Each link will lead you to a different list of tickets called a report. Trac has dozens of predefined reports available. They each help surface specific types of tickets or tickets with specific action based keywords. You can also create your own report at any time by clicking design your own query. While they do not identify tickets based on keywords, the me section is very useful. You can use this to find tickets that you’ve created.

16:51
Tickets with patches that you’ve submitted, tickets that you’ve participated in, and tickets that you are watching. When logged into Trac and viewing any ticket, you’ll notice a star in the top left hand corner. Clicking this on a ticket will add that ticket to your watchlist. Let’s click on the latest ticket report to see how we would favorite a ticket. Let’s say we have a particular interest in this second ticket. You can see the star here in the top left hand corner of the ticket description. Clicking that will watch that ticket. On clicking it will on watch it at the bottom near the common field. There’s also another way to watch this ticket. your avatar will be added here and you’ll be noted as someone that is paying attention to this ticket. If there are others also watching this ticket there will be displayed next to your avatar.

17:53
You’ll notice that below the comment field is the exact same form that you use to create a new ticket. You can modify any field on this ticket just as you would when you are creating a new one. You’ll also notice a few new fields that are available once the ticket has been created. These represent different actions that can be taken on a ticket once it’s been created. Let’s take a look at the available list of ticket resolutions. There are currently five available resolutions in Trac invalid won’t fix works for me, maybe later and reported upstream. Invalid is the default catch all resolution. This indicates that the ticket cannot be addressed third Trac, your most frequently see this applied to tickets that are better suited for the wordpress.org support forums. Works for me is used when a reported bug cannot be reproduced by other contributors. Well fix is used when a decision is made by trusted contributors to not address an issue. This is usually found on tickets that either fall outside of the project goals address a specific edge case that is deemed acceptable, or a feature that has been rejected for core inclusion. Maybe fix is similar to one fix. However, this is used when a ticket could potentially be reevaluated if circumstances change in the future. And finally reported upstream. This is used when a ticket must be addressed elsewhere before the suggested changes can be included in WordPress. For example, a report about a bug in the Block Editor should be reported to the Gutenberg repository on GitHub, or an external library that is bundled in core such as PHP mailer. These external libraries often have their own canonical repository that’s maintained elsewhere. The changes must be made to those repositories before being merged into core. Last field is used for marking one ticket as a duplicate of another. It’s common for issues to be reported multiple times. Closing a ticket as a duplicate helps direct all conversation to a single location. When marking a ticket as a duplicate, a comment noting the action will be left on both tickets. The duplicate ticket will also be closed. That wraps up everything that we’re going to cover in this video. You should now have everything you need to contribute to WordPress through Trac.