• Bugzilla
• TriageTraining

Triage Training

Used for training new triagers and upskilling existing project developers on a group basis, rather than individually (scale!).

Use in combination with Bugzilla do's and don'ts, The Perfect Ports Issue and Bugzilla Keywords

Specific examples demonstrating each will be added in future iterations

Field names and values are in italics

Introduction

Don't Panic!

This is a lot to take in, but there's a method to our madness!

Rationale

Issue triage and management, and those that participate in that space, sits broadly at the intersection, and in-between, users and project members. Fundamentally, this means it:

• Is a public, and human-facing role.

• Is about and relies on effective communication

• Conveys and exemplifies what a project and its people value
• Influences and affects how a project and its people are perceived.

Accordingly, the raison d'être (¹) of issue triage and management is ostensibly about enabling and facilitating others, focusing on creating and improving clarity and promoting understanding and encouraging action.

With outcomes in mind, the following high-level elements are critical to consider:

• Objectivity <---> Subjectivity

• Facts <---> Speculation

• Global <---> Local Outcomes

• Asking <---> Directing

• Teaching <---> Telling

• Brevity <---> Detail

More concretely, issue triagers should:

• Remove 'themselves' from the equation. Triage is not about you. Focus on issues out there, not people and personalities.

  • Especially when writing Comments

• Minimise and resist, ideally entirely, the urge to speculate.

• Orient themselves around the question: what's needed to progress?

• Think about their own assumptions, and those of others involved, before taking action.
• Consider non-technical elements involved as important as the technical elements.
• Consider the value of all participants, not just certain individuals or groups of people.

On-boarding Process

This on-boarding process is designed to be as self-directed and flexible as possible, to minimise "blocking" steps, synchronous communication, and enabling you to determine how you achieve your goals.

Triage team candidates should be proactive, communicating with other team members or their mentors if and when you need advice, support or knowledge to progress.

The overall process for bringing on triage team members is as follows:

1. Email Bugmeister to express your interest in joining the Triage Team (thanks!)

   • You don't necessarily have to be a FreeBSD committer!
2. Orient yourself and get ready (knowledge!)
3. Join the team (yay!)
4. Practice (experience!)
5. Mentor someone else (skills!)

Frequently Asked Questions

• …

Orientation: On your marks…

The goal of Orientation is understanding of purpose, expectations and laying a solid foundation knowledge to build and expand on.

1. Read and take notes on Bugzilla guides and resource documents to familiarise yourself with terminology, processes and expectations.

   • These notes will form the basis of your first contribution in the last step.
   • Don't worry if you don't understand all of this at one go!
2. Schedule a catch-up with your mentor on IRC.
   • Review and discuss your notes and any questions you have.
3. Let your mentor know if you'd like to proceed or how we can help you make a decision.
4. If you're happy to proceed, make at least one improvement to existing issue management guides and documents, based on your notes and discussion (easy quick win!).

Setup: Get set...

The goal of Setup is You are part of a team.

1. Join #freebsd-bugs on Libera Chat IRC

2. Create a Bugzilla account if you don't already have one (email is public, recommend: use a dedicated account)

3. Set your Real Name in Bugzilla User Preferences

4. Get added to the Bugzilla Triager Group (freebsd_triage), which adds the editbugs permission.

   • Ask on IRC if this hasn't been done yet.

5. Get added to the Bugzilla Triage Team list on the Wiki.

   • Optional, but recommended: Create a Wiki Account

6. Optional: Subscribe to Bugzilla/* Wiki pages to get updates on changes to them

7. Let the community know you've joined the team
   • This could be an email to a mailing list cc Bugmeister or similar.

Free Practice: Go!

The goal of Free Practice is: demonstrate what has been learned and participate consistently with confidence.

This stage is where you put what you have learned in Orientation into practice in a low pressure way. The idea is not necessarily to triage all the things completely and perfectly, but rather to build confidence and habits, and becoming familiar with the different kinds and forms that issues take.

Completion of the Practice stage has no strict minimum time or how many issues triaged requirement, can take as long as needed, but we anticipate a consistent practice period of 1-2 months should be sufficient.

Key: Demonstrating regular progress and proactive communication.

Practice should focus on:

• Proactive communication. Ask questions, for help or support if and when you need it.
• Consistent activity. Don't over do it; it's better to build up over time than burn out.
• Consistent process and workflow (cycle).
• Familiarity with tooling.

Your primary resource during practice is this document and the guides read during orientation and your team/mentor on IRC or elsewhere.

Set aside a regular and consistent amount of time to practice triaging issues. Some good (but optional) places to start are:

• Newly created ports issues

• Issues on the freebsd-ports-bugs mailing list

  • The default Assignee: for new issues in Ports & Packages component is this mailing list

  • Subscribing to freebsd-ports-bugs and reviewing issues as they come in via an email client is easier and faster than browsing the archives as incoming mail is essentially a 'new ports issues queue', that you can delete as you triage.

• Issues posted (by VimDiesel bot) in the #freebsd-bugs IRC channel

  • These issues are for all products and components.

General

• Assume nothing, verify everything.
• If you're not sure, don't change it until you are.
• Teach/educate others while you triage (See #teach items below).

• Assignee should only be @FreeBSD.org contributors, or Triagers (you), when closing issues with !FIXED resolutions.

High Signal, Low Noise

• Don't add comments unless necessary. Necessary means other actions taken are not self-explanatory, and require additional detail or context, as a comment.

• When making changes that aren't self-explanatory, add a (terse, factual) comment in ^Triage: <comment> format (See Triage Templates)

• Make as many changes in one go as possible before submitting (Reduces email traffic).
• If CC'ing people on issues, do so only when its clear and obvious that they need or would like to be notified.

  • Tip: Check issue History link, don't re-add users to CC if they've removed themselves previously.

Basics

Statuses

• New: New issue, not yet triaged.

• Open: Initial triage complete (correct and complete Component, Keywords and other metadata).

  • This does not denote that the PR is apt -- only that it has a valid form. See Notes About Open.

• In Progress: Has a real Assignee currently set, and work has started (a patch, a review, etc).

  • An issue can't be In Progress without a real Assignee, even if the issue has had some updates to it (such as a patch added).

  • If an issue is currently In Progress, and the Assignee is not a real person (team, mailing list), reset Status to Open.

    • Fixing these is listed as a task in Bugmeister/BugmeisterQA.

• Closed: Initial issue ;as reported; is no longer true (by way of rectification, obsolescence, duplication, invalidation, etc).

  • Ideally this is confirmed by the original Reporter prior to close.

Resolutions

• FIXED: Issue resolved by way of a change that has been made, a commit, documentation update etc.

  • Not appropriate for issues that are no longer reproducible where a change cannot or has not been identified.

• Overcome By Events: Issue as reported or proposed course of action is no longer useful or relevant due to external events.

• Works as Intended: Behaviour as described/reported is explicitly intentional and can not or will not be modified. See Also: Not A Bug.

• Not Enough Information: Insufficient information to triage, assign, reproduce or resolve. Note: See Also: Unable to Reproduce.

• Unable to Reproduce: Given available (sufficient) information, issue as reported cannot be reproduced.

• Not Accepted: An issue as reported, with a proposed change (for example: patch), has been assessed, reviewed and a decision made not to accept the change.

• Not A Bug: Issue or behaviour as reported is not is 'not actually an issue'. Use also for 'general support' requests.

• DUPLICATE: An existing, previously reported and separate issue is exactly the same (conditions, behaviour, etc) as this one.

• Feedback Timeout: Additional information was explicitly sought, and was not received in a timely manner.

Metadata: Correct and Complete

These items apply to all issues, in all (any) state.

• Clean up & "normalize" issue Summary

  • Example: Remove [tags]
• Improve summary where possible
  • Shorter is better, unless it removes meaning or reduces clarity
  • As complete a description of bug / issue as possible

  • Remove superfluous verbiage including tags, symbols (->), literal category/portname, etc.

• Check for correct & fix incorrect Product & Component

• Check comments for items that should be in fields. For example:

  • FreeBSD version mentioned, but Version field not set

  • Architecture mentioned, Hardware field(s) not set (be careful, just because it was reported for amd64, doesn't mean it only applies to amd64)

  • Changelog URL mentioned, not set in URL field

  • External bug/commit/PR references mentioned, not added to See Also field

• Check for "related issue ID's" in comments. Add to See Also, Depends On, or Blocks fields

• Add relevant Keywords

• Set Importance fields (Priority, Severity) based on scope.

  • Security issues get Normal priority, everything else the default (---)

  • Feature/Version Updates, Severity -> Affects only me

  • Bugs Unverified or Unknown Scope, Severity -> Affects only me

  • Bugs that are Conditional Scope, Severity -> Affects some people

  • Bugs that are Unconditional Scope, Severity -> Affects many people

• Set Assignee to maintainer, if the maintainer is a @FreeBSD.org developer. Request/set maintainer-feedback ? <maintainer-email> flag, if not set

• If commit revisions are mentioned, add committers of those revisions to CC, if relevant.

• If you know certain people are interested in, or should be notified of issues "like this", add those people or teams to CC. For example:

  • One or more primary and recent committers to the port or base component in question

  • ports-secteam@ for ports security issues

  • python@ for new python ports or ones with pending updates

Notify Relevant/Interested Contributors

• Add contributors (MAINTAINERS, Committers, Teams) to CC if they are/were involved or relevant to the issue.

  • Set contributor as Assignee if they are a Committer, the only person involved, and originated the issue. Example: Bug 239963: pkg-plist regression.

  • Use cgit to identify committer(s) involved in a change.

Examples

• Bug 235890: Circular dependency in emacs/mailutils (See Comment 3 and 4)

Closed/Closing Issues

• Issue has a real person Assignee when closed

  • Assign to user that resolved the issue

    • Resolved means resolved by way of a change (commit, etc), or resolved by way of Closing the issue (Status -> Closed)

    • Issues closed with Resolutions not FIXED, set Assignee to user that closed (or commented that it should be closed)

• Use the most correct/accurate Resolution possible. Note: Some resolutions do overlap sometimes, use informed/rational judgment.

• When closing Duplicate issues, always close the newer issue as a duplicate of the older issue, unless the newer issue has more of the information/patches/comments

Ports Specific

• If Reporter is MAINTAINER, set maintainer-approval attachment flag value to + (#teach)

• Version update:
  • Check for upstream changelog URL, add to URL field

  • Bugfix or security release: Set merge-quarterly flag to ?

  • Security release: Request VuXML entry (#teach)

• If port Makefile gives an error, specify target in summary, like: Fails to <target>: $error-summary

• New ports are normally not merged to quarterly

  • there may be exceptions (brief discussion in FreeBSD Bugzilla).

Base Specific

• Where version branch(es) is/are verified to be affected, add/set mfc-stableXX issue flag(s) to ?

Resources

• Triage comment templates for common issue situations and actions

Notes

• Open means "someone has done the work to make sure this is a valid PR."

  • It does not mean the PR itself is apt. For instance, see the following from 2018:

For bugs matching the following conditions:
- Status == In Progress
- Assignee == "[email protected]"
- Last Modified Year <= 2017

Do
- Set Status to "Open"

This was not long after 215258 was filed.

---

CategoryContributing CategoryHowTo