====== 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/DosAndDonts|Bugzilla do's and don'ts]], [[Bugzilla/ThePerfectPortsIssue|The Perfect Ports Issue]] and [[Bugzilla/Keywords|Bugzilla Keywords]] Specific examples demonstrating each will be added in future iterations Field names and values are in //italics// ====== Introduction ====== 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// (((Reason for being: https://en.wikipedia.org/wiki/Raison_d%27%C3%AAtre))) 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: - Email [[/Bugmeister]] to express your interest in joining the Triage Team (thanks!) - Orient yourself and get ready (knowledge!) - Join the team (yay!) - Practice (experience!) - 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. - Read and //take notes// on [[/Bugzilla|Bugzilla guides and resource documents]] to familiarise yourself with terminology, processes and expectations. * **Important**; These notes will form the basis of your first contribution in the last step. - Schedule a catch-up with your mentor on IRC. * Review and discuss your notes and any questions you have. - Let your mentor know if you'd like to proceed or how we can help you make a decision. - 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**//. - Join #freebsd-bugs on Libera Chat IRC (ircs:%%//%%irc.libera.chat/#freebsd-bugs) - Create a Bugzilla account if you don't already have one (email is public, recommend: use a dedicated account) - Set your Real Name in [[https://bugs.freebsd.org/bugzilla/userprefs.cgi?tab=account|Bugzilla User Preferences]] - Get added to the Bugzilla Triager Group (freebsd_triage), which adds the ''%%editbugs%%'' permission. * Ask on IRC if this hasn't been done yet. - Get added to the [[/Bugzilla|Bugzilla Triage Team]] list ('trial') on the Wiki. * Optional, but recommended: [[Wiki/About|Create a Wiki Account]] - - 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 places to start are: * [[https://bugs.freebsd.org/bugzilla/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=Ports%3A%20Needs%20Triage%20%28New%29&sharer_id=27730|Newly created ports issues]] * Issues on the [[https://lists.freebsd.org/archives/freebsd-ports-bugs/|freebsd-ports-bugs mailing list]] * The default Assignee: for new issues in Ports & Packages component is this mailing list * [[https://lists.freebsd.org/subscription/freebsd-ports-bugs|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|VimDiesel]] bot) in the #freebsd-bugs IRC channel (ircs:%%//%%irc.libera.chat/#freebsd-bugs) * 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// can 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 [[#templates|Triage Templates]]) * Make as many changes in one go as possible before submitting (Reduces email spam). * 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). * **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// * **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 (->), 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 * [[/PortsSecteam|ports-secteam@]] for ports security issues * [[/Python|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: [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=239963|Bug 239963: pkg-plist regression]]. * Use [[https://cgit.freebsd.org/|cgit]] to identify committer(s) involved in a change. ===== Examples ===== * [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=235890|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 most/all 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 [[Ports/QuarterlyBranch|quarterly]] * there may be exceptions ([[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=267982#c16|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 ====== * [[Bugzilla/TriageTemplates|Triage comment templates]] for common issue situations and actions ---- {{tag>Contributing}} {{tag>HowTo}}