Skip to content

Instantly share code, notes, and snippets.

@juanmaguitar

juanmaguitar/wordpress-trac-keywords-guide.md

Last active January 20, 2026 21:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save juanmaguitar/eb331ad4464c33f961c36bfb049f5ad1 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save juanmaguitar/eb331ad4464c33f961c36bfb049f5ad1 to your computer and use it in GitHub Desktop.
Download ZIP
Complete WordPress Trac Keywords Guide - Meanings and Usage
Raw
wordpress-trac-keywords-guide.md

Complete WordPress Trac Keyword Guide

A comprehensive guide to all WordPress Trac issue labels/keywords, their meanings, and when to use them.

Overview

WordPress Trac keywords are not like generic tags on a blog post. They are a defined list of keywords that describe a ticket's current status in the development workflow and are used to build important reports. All keywords belong to one of two groups: status-based and action-based.

Typical Workflow Progression

The standard workflow follows this sequence:

reporter-feedback 
  ↓
needs-patch 
  ↓
has-patch / needs-testing 
  ↓
needs-unit-tests / needs-docs 
  ↓
dev-feedback / needs-review 
  ↓
tested / commit

Quick Reference: Testing & Triage Cheat Sheet

After Patch Testing (not bug reproduction)

Decision tree for patch testing:

  • ❌ Isn't the patch passing? → changes-requested
  • ❌ Isn't the patch applying? → needs-refresh
  • ❓ Isn't clear the instructions for testing? → needs-test-info
  • 📸 Do we need a screencast or screenshot to better understand? → needs-screenshots
  • ✅ Is clear and we have added very clear instructions so any future reviewer can use them? → has-test-info
  • ✅ Have we added screenshots or screencast showing the problem? → has-screenshots
  • 🧪 Do we think it should have Unit Testing along with the code? → needs-unit-tests

After Bug Reproduction

Decision tree for bug reproduction:

  • ❓ Isn't clear the instruction for reproducing? → reporter-feedback
  • ✅ It's clearly reproducible and we think it is a bug? → dev-feedback
    • ⚠️ Note: Only component specialists, component maintainers, and core committers can add needs-patch after testing, because we have to be 100% sure that this is a bug and not something expected
  • 🤔 Are we unsure that this is a bug but the instructions are clear? → 2nd-opinion

⚠️ MOST IMPORTANT RULE

Remove the needs-testing label once you have selected any option!

Patch-Related Keywords

has-patch

  • What it represents: A patch file has been attached to the ticket
  • When to use: After uploading a patch to fix the issue. Since patch uploads don't trigger notifications, always add a comment with [attachment:filename] to link to your patch
  • Note: Often appears with asterisk/disabled in UI as it's frequently used

needs-patch *

  • What it represents: The ticket has been confirmed as a bug/issue and requires a patch to fix it
  • When to use: When a reproducible bug needs someone to write code to fix it (and unit tests, if applicable)
  • Note: Disabled/asterisk indicates it's a critical workflow keyword

needs-refresh

  • What it represents: The existing patch doesn't apply cleanly against the current codebase
  • When to use: When testing a patch and it fails to apply due to conflicts with recent code changes. The patch needs to be updated based on the latest available code

changes-requested

  • What it represents: Feedback has been provided and the attached patch needs to be updated
  • When to use: When reviewers have provided specific feedback that requires modifications to the existing patch

Testing Keywords

needs-testing *

  • What it represents: The patch requires testing by the community to ensure it works and doesn't introduce bugs
  • When to use: When a patch is ready but needs community verification before it can be committed
  • Note: Disabled/asterisk indicates it's a critical workflow keyword; triggers dedicated Trac reports

has-test-info

  • What it represents: The ticket contains adequate testing instructions or step-by-step information
  • When to use: Manually added during triage when step-by-step instructions (written, video, or GIF) are present within the ticket
  • Note: Part of Test Team workflow; renamed from "has-testing-info" to avoid search conflicts

needs-test-info

  • What it represents: The ticket lacks sufficient testing instructions or information needed to properly test the issue/patch
  • When to use: When the ticket needs more detailed steps to reproduce or test the issue
  • Note: Part of Test Team workflow; renamed from "needs-testing-info" to avoid search conflicts with "needs-testing"

has-unit-tests

  • What it represents: Unit tests have been provided for the ticket
  • When to use: After unit tests are written and attached to verify the patch

needs-unit-tests

  • What it represents: Unit tests are needed to verify and test the patch
  • When to use: When tests are particularly needed for a ticket to proceed, especially for core functionality changes

Design Keywords

needs-design

  • What it represents: A designer should create a prototype/mockup of how changes should look/behave before code is written
  • When to use: When requesting new design work or prototypes before implementation begins
  • Key distinction: Use this for creating new designs

needs-design-feedback

  • What it represents: A designer should review and give feedback on the proposed changes
  • When to use: When design already exists or is proposed, and you need a designer's review or opinion
  • Key distinction: Use this for reviewing existing designs
  • Note: Merged from older 'ux-feedback' and 'ui-feedback' keywords (2018); triggers dedicated Design team reports

Feedback Keywords

reporter-feedback

  • What it represents: A response is needed from the original ticket reporter
  • When to use: When you can't reproduce the issue and need more information from the person experiencing the problem. Further investigation is unlikely without their response

dev-feedback *

  • What it represents: A response is needed from a core developer or trusted member of the development community
  • When to use: When you need technical input from experienced developers, or when double sign-off is required (e.g., backporting changes during RC)
  • Note: Disabled/asterisk indicates it's a critical workflow keyword; triggers dedicated reports

2nd-opinion

  • What it represents: A second opinion is needed from other contributors before taking action
  • When to use: When you're uncertain about the approach or resolution and want additional input from the community
  • Often used with: close or reporter-feedback keywords

Status Keywords

close

  • What it represents: The ticket is a candidate for closure with a disposition other than "fixed" (e.g., wontfix, duplicate, invalid)
  • When to use: When you believe the ticket should be closed but want community agreement first
  • Note: Often seen with reporter-feedback or 2nd-opinion; otherwise, the ticket would just be closed directly

Documentation Keywords

needs-docs

  • What it represents: Inline code documentation (PHPDoc/DocBlocks) is needed for developer reference
  • When to use: For placeholder tickets for individual files, or patches with new functions that need documenting before commit
  • Target audience: Developers (appears in Code Reference at developer.wordpress.org)

needs-user-docs (also called needs-codex)

  • What it represents: End-user documentation in the Codex/HelpHub needs updating or expanding
  • When to use: When changes affect how users interact with WordPress and need documentation updates
  • Target audience: WordPress users and site administrators
  • Action: Remove keyword once documentation is updated

needs-dev-note

  • What it represents: A developer note should be written for the make/core blog
  • When to use: For significant changes including new functionality, large refactors, or breaking changes that developers need to know about
  • Note: Applied during release cycles for tickets warranting dev notes

has-dev-note

  • What it represents: A developer note has been published for this ticket
  • When to use: Replaces needs-dev-note once the note is published; include a link to the note in a comment

add-to-field-guide

  • What it represents: This change should be mentioned in the WordPress version Field Guide
  • When to use: For changes that don't warrant a full dev note but should be included in the "But Wait, There Is More!" section of the Field Guide
  • Format: Listed as: "Component Name: Trac Ticket Summary (#Trac-Number)"
  • Timing: Field Guides are published around RC1 for each major release

Privacy & Copy Review Keywords

needs-privacy-review

  • What it represents: The Privacy team needs to review the privacy implications of the suggested changes
  • When to use: When changes involve user data collection, storage, or processing that may have privacy implications

has-privacy-review

  • What it represents: The Privacy team has reviewed and provided input on the privacy implications
  • When to use: After the core privacy team has completed their review

needs-copy-review

  • What it represents: Input is needed from a copywriter regarding the suggested verbiage/text changes
  • When to use: When the ticket involves user-facing text that should be reviewed for clarity, tone, or accuracy

has-copy-review

  • What it represents: A copywriter has reviewed and approved the text changes
  • When to use: After copy review is complete and any necessary changes have been made

Screenshot Keywords

needs-screenshots

  • What it represents: Screenshots are needed to document UI changes
  • When to use: For patches and commits that change the user interface
  • Requirements: Provide screenshots for both desktop and mobile (at minimum)
  • Action: Remove keyword once screenshots are uploaded to the ticket or posted to make/flow

has-screenshots

  • What it represents: Screenshots have been provided for the UI changes
  • When to use: After uploading adequate screenshots showing the changes

Important Notes About Keywords

  1. Keywords marked with asterisk (*) and disabled in the dropdown (needs-patch, dev-feedback, needs-testing) are critical workflow keywords that trigger important reports and should be used carefully

  2. Keywords are not tags: They have specific defined meanings and describe the ticket's current status in the development workflow

  3. Keywords build reports: They're used to automatically generate reports that different WordPress teams rely on for their work

  4. Update keywords as work progresses: Always adjust keywords as the ticket moves through different stages

  5. Hover for help: On the Trac system, hovering over keywords shows tooltips with descriptions

  6. Two main categories: Keywords belong to either status-based (describing current state) or action-based (describing needed action) groups

Sources

Last Updated: January 2026
Compiled from: WordPress Core Contributors Handbook and Testing Handbook

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment