Hi, my name is Jonathan Desrosiers. I ama 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. If you're not familiar, Tracis the ticket tracking software that the
WordPress project uses to make changesto the code base. Every change made to
WordPress is always accompanied by aticket and Trac. To use Trac, you will
require a WordPress.org account. Onceyou have one, you can log into Trac
using the same credentials. Afterwatching this video, you will have all
the information you need to open a newticket or to contribute to WordPress by
helping to manage existing ones. Beforewe get started, it's very important to
note that security vulnerabilitiesshould never be posted publicly, even
when reporting the issue to theWordPress team. Please respect the
project's security policy by disclosingany vulnerabilities responsibly and
privately to the project's hacker oneorganization Trac is not the appropriate
place to report securityvulnerabilities. Okay, let's get
started. When you first open Trac,you'll be presented with this screen.
You may be tempted to ignore this pagebecause there was a lot of text, but I
recommend that you return here later andtake a few minutes to read through it.
There are many links to helpfulresources that will help you better
understand the different aspects ofcontributing 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 thetop of this page, you'll see several
bullet points providing tips to create abetter more descriptive ticket. For
example, you should always confirm thatthe issue you are reporting can be
reproduced on the latest version ofWordPress. There are also some specific
types of tickets that should be reportedto different locations. One example of
this is a ticket that reports a bug orfeature requests for the Block Editor.
Those are better off being reported tothe Gutenberg repository on GitHub.
Since the changes must be made therebefore being merged into the WordPress
core code base through Trac. Like theprevious screen, I recommend that you
return here later and take the time toread through these tips. Before creating
a new ticket, it's good practice tosearch for a pre-existing ticket that
identifies the same issue that you arereporting. It's not uncommon for an
issue to have been reported already byanother contributor. Sometimes there are
even patches that attempt to fix theissue for you to test. Doing this will
help cut down the amount of tickettriaging that other core contributors
need to perform. To search for apre-existing ticket on track, use the
search field at the top of the screen.We'll talk a little bit more about using
track search later on in this video.Let's scroll down and look at the form
and talk about what each fieldrepresents. The first field is the
ticket summary. The summary isessentially the title or name of the
ticket and will be displayed along withthe ticket number in most places
throughout Trac. Your ticket summaryshould clearly state the problem or
feature.
You'll notice that as you enter yourinformation into the form, the preview
of the ticket is displayed. This is ahelpful way to proofread and review your
ticket before hitting submit. Next isthe ticket description. The ticket
description is where you would enter allof your information about the bug that
you are reporting or the enhancementthat you are requesting. It's important
to be very detail oriented and provideas much information as possible. If
you're reporting a bug, please provideexplicit steps that someone else can
take to reproduce the issue reliably.The ticket description should not
describe a proposed solution orimplementation. The solution to the
problem or the best way to implementenhancement will change evolve over
time, as more contributors providefeedback. This helps to keep the ticket
description the same over time whilestill remaining accurate. It also allows
contributors to follow the progressionof proposed changes in a chronological
way within the tickets comments. For thepurpose of this video, let's assume that
we're reporting a bug. I've gone aheadand created a fake bug description
already. Moving down, you'll notice thatthe next two fields are crossed out in
disable. These two fields can only bemodified by community members with
commit access, who are also known ascommitters or trusted core contributors.
This includes but is not limited toofficial component maintainers bug
gardeners or members of major and minorrelease teams. The first disabled field
is milestone. The Milestone representsthe version of WordPress where the
ticket is expected to be resolved. Bydefault, the milestone is set to a
waiting review. We'll talk more aboutthe different values for milestone a bit
later on. The second disabled field ispriority. Priority is the seriousness of
a bug report or ticket in the eyes ofthe project. Below that is severity.
Severity is the seriousness of theticket in the eyes of the reporter.
Generally, severity is a judgment of howbad a bug is, while priority is its
relationship to other bugs. Please bereasonable when selecting the severity
of a ticket. Just because the bug isaffecting your site in a negative way,
does not mean it is a blocker, criticalor even major severity. And selecting
the highest severity will notnecessarily result in your ticket being
fixed any faster. The overwhelmingmajority of tickets should fall into the
normal severity. To the left is our nextfield 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 anavailable ticket type feature
development for the upcoming majorreleases center around task tickets,
which are major features or importantenhancements that have been blessed by a
release squad or project lead. For thisreason only the groups mentioned before
are allowed to create task tickets. Abug is an error or unexpected result.
performance improvements in codeoptimizations are considered
enhancements and not defects.enhancements are simple improvements to
WordPress, such as the addition of ahook or an improvement to an existing
feature. Since we're creating a bughere, 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, thisshould be set to the earliest effective
or applicable version. If you're able totest older versions of WordPress,
working backwards to identify the firstversion of WordPress that experiences
the issue you are reporting is veryhelpful. This could aid in identifying
the exact code change that caused theproblem. If you're not able to selecting
the version of WordPress that you arecurrently using is fine. However, if
another contributor is able to workbackwards and identify the first version
of WordPress that experiences the issue,please do not change this version to a
future version. Trunk should only beused if the ticket addresses unreleased
code in the WordPress developerrepository. If you are using the beta
tester plugin, it's also possible thattrunk applies to your bug. For the sake
of this video, let's say that this bugwas introduced in WordPress 5.6, which
was the last major release beforerecording this video.
The next field is component. For thepurposes of contributing. WordPress is
organized into roughly 60 componentsrepresenting well defined functional
areas of core. This helps identify whichareas of WordPress are affected by a
specific ticket and groups those ticketstogether for contributors. Each
component has its own ticket report ontrack is listed on the WordPress core
components page, and links off to itsown page where maintainers can add
specific information about contributingto that component. Further down, you'll
find a list of component maintainers.Each component has one or more
maintainers maintainers are responsiblefor triaging new tickets, looking after
existing ones curating roadmaps,providing feedback to other
contributors, and co working with othercomponent maintainers. To help tickets
be solved in versions of WordPress.Longtime maintainer is often have a very
deep understanding of a componentshistory and how their component impacts
other areas of WordPress. On Track,you'll be able to identify component
maintainers by this badge next to theirname. This will appear whenever a
contributor comments on a ticket thatbelongs to a component that they helped
maintain. You may also encounter a fewother labels, such as this core
committer label or this lead developerlabel. General is the default component
It's always better to select a morespecific component over a more
generalized one whenever possible. Forthis ticket, let's select the media
component. Below the component field,you'll find focuses focuses are broad
concepts that help break tickets down byspecialties and skills rather than
functional areas of core. For example,accessibility is not a specific area of
core. Instead, it's something thatshould be considered throughout the
entire user experience. A ticket aboutinline documentation should still
receive the attention of contributors toa more specific area of core. But anyone
who focuses on inline documentationshould still be able to provide
feedback. For our example bug report,let's assume that the inline
documentation associated with the codeproducing the unexpected behavior is
inaccurate. While our ticket belongs tothe media component. Selecting this
focus will potentially help inlinedocumentation contributors discover the
ticket so that they can provide anysuggestions or guidance that they may
have.
To the left of focuses, you'll findworkflow keywords. Each keyword has a
specifically defined meaning. Allkeywords belong to one of two groups,
status based and action based. At thetime of this recording, there are
roughly 30 keywords that are officiallyrecognized. I'm only going to cover a
handful of keywords in this video. Thefull list of keywords can be found on
the Trac workflow keywords page in theWordPress Core handbook. I recommend
reading through the list in full afterwatching this video. Let's assume that
our ticket would require changes to acore function, I'm going to add the
needs unit test keyword. This indicatesthat any changes associated with this
ticket should be accompanied by unittests. Providing unit tests with a
ticket will usually help a ticketprogress more quickly. unit test can
confirm the new desired behavior isbeing achieved while preserving all of
the correct behaviors that currentlyexists. Let's assume that I have a patch
to attach to this ticket. I'm going tocheck the I have files to attach to this
ticket checkbox so that I am prompted toupload my files after creating the
ticket. I'm also going to add the haspatch keyword. This indicates that I
working patch proposing changes toaddress the problem or enhancement
describing the ticket is attached. Ifyou do not have a patch to attach to the
ticket, you can add the needs patchkeyword. It's not uncommon for a patch
to become stale throughout the lifecycleof a ticket. When a patch becomes stale,
it will no longer apply to the currentversion of trunk automatically and will
need to be refreshed so that othercontributors can review and test the
changes. When this happens, the needsrefresh keywords should be added to the
ticket so that contributors can identifywhich tickets need patches to be
refreshed. When adding the needs refreshkeyword, please leave the has patch
keyword as the ticket does in fact havea patch. It has just become dated and
need some more attention. Sometimesrefreshing a patch is very trivial. But
other times the code changed in thepatch was altered while addressing
another ticket and will need to berecreated from scratch. Let's also
assume that I have screenshots to attachdemonstrating the problem before and
after the patch is applied. When this isthe case that has screenshots keyword is
appropriate. best effort should alwaysbe made to include before and after
screenshots whenever modifications aremade that result in visual changes. If
you do not have screenshots to attachbut feel that they would be useful to
help document this problem. The needsscreenshots keyword should be used. I'm
also going to add the second opinionkeyword. While I'm attaching a patch
that fixes the issue. I'm not sure thatthe proposed solution is best and I
would appreciate a second opinion fromanother contributor. If at any point you
encounter a keyword that you're not sureof the meaning just hover over the
keyword a tooltip will appear with ashort description of the what the
keyword is meant for. Okay, I think ourticket is ready to go. Let's scroll down
and give it a proofread before clickingCreate ticket looks good. Let's go. If
you check the I have files to attach tothis ticket checkbox. You'll be
presented with this screen afterclicking Create ticket. If you forgot to
select the checkbox, it's okay. You caneasily 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 linkto the file in an external file storage
service like cloud up or Dropbox may bemore convenient. Those links almost
always become dead links. Eventually,files added directly to Trac will always
be preserved indefinitely, ensuring thatcontributors visiting the ticket today,
next week, next year, or even 10 yearslater, we'll be able to access the files
that provide the needed context toresolve the ticket. Keywords almost
always need to be updated after addingattachments to a ticket. Make sure to
return to the ticket screen and updatethe keywords appropriately after adding
your attachments. That's it. That's allyou need to know to open a ticket on
track. Easy right.
Now that you know how to create your ownticket, 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 alwaysbring up this overlay. Each link will
lead you to a different list of ticketscalled a report. Trac has dozens of
predefined reports available. They eachhelp surface specific types of tickets
or tickets with specific action basedkeywords. You can also create your own
report at any time by clicking designyour own query. While they do not
identify tickets based on keywords, theme section is very useful. You can use
this to find tickets that you'vecreated.
Tickets with patches that you'vesubmitted, tickets that you've
participated in, and tickets that youare watching. When logged into Trac and
viewing any ticket, you'll notice a starin the top left hand corner. Clicking
this on a ticket will add that ticket toyour watch list.
Let's click on the latest ticket reportto see how we would favorite a ticket.
Let's say we have a particular interestin the second ticket. You can see the
star here in the top left hand corner ofthe ticket description. Clicking that
will watch that ticket unclicking itwill unwatched it at the bottom near the
common field. There's also another wayto watch this ticket. Your avatar will
be added here and you'll be noted assomeone that is paying attention to this
ticket. If there are others alsowatching this ticket, they will be
displayed next to your avatar. You'llnotice that below the comment fields is
the exact same form that you use tocreate a new ticket. You can modify any
field on this ticket just as you wouldwhen you are creating a new one. You'll
also notice a few new fields that areavailable once the ticket has been
created. These represent differentactions that can be taken on a ticket
once it's been created. Let's take alook at the available list of ticket
resolutions. There are currently fiveavailable resolutions in Trac invalid
won't fix works for me, maybe later andreported upstream. Invalid is the
default catch all resolution. Thisindicates that the ticket cannot be
addressed through Trac. You'll mostfrequently see this applied to tickets
that are better suited for theWordPress.org support forums. Works for
me is used when a reported bugs cannotbe reproduced by other contributors.
Well fix is used when a decision is madeby trusted contributors to not address
an issue. This is usually found ontickets that either fall outside of the
project goals address a specific edgecase that is deemed acceptable, or a
feature that has been rejected for coreinclusion. Maybe fix is similar to one
fix. However, this is used when a ticketcould potentially be reevaluated if
circumstances change in the future. Andfinally reported upstream. This is used
when a ticket must be addressedelsewhere before the suggested changes
can be included in WordPress. Forexample, a report about a bug in the
Block Editor should be reported to theGutenberg repository on GitHub, or an
external library that is bundled in coresuch as PHP mailer. These external
libraries often have their own canonicalrepository that's maintained elsewhere.
The changes must be made to thoserepositories Before being merged into
core last field is used for marking oneticket as a duplicate of another. It's
common for issues to be reportedmultiple times. Closing a ticket as a
duplicate helps direct all conversationto a single location. When marking a
ticket as a duplicate, a comment notingthe action will be left on both tickets.
The duplicate ticket will also beclosed. That wraps up everything that
we're going to cover in this video. Youshould now have everything you need to
contribute to WordPress through Trac