Skip to content

Triage Process

Jump to bottom
Simon Adorf edited this page Jul 7, 2025 · 16 revisions

This document outlines the complete workflow for managing project issues and pull requests, from initial creation through resolution. It defines the status lifecycle, triage process, and automation rules to ensure issues are properly tracked, actionable, and efficiently directed to the right people.

Why Issue Management Matters

Effective issue management helps us:

  • Maintain a healthy and organized issue backlog
  • Ensure user concerns are addressed promptly
  • Direct resources efficiently
  • Keep the development process flowing smoothly

Issue Status Lifecycle

Each issue must have one of the following statuses:

  • Needs Triage

    • Initial state for new issues that require review and categorization
    • Issues need to be assessed for validity, duplicates, and proper labeling
    • Requires triage manager attention to move to next status

  • Needs More Information

    • Issue lacks sufficient details to take action
    • Waiting on reporter to provide additional context, reproduction steps, or clarification
    • Should be followed up on if no response after 1 week

  • Todo

    • Issue is properly triaged, scoped, and ready for development
    • Has all necessary information, clear acceptance criteria, and appropriate labels
    • Issues with this status form the backlog and must be assigned to a release before work begins

  • In Progress

    • Active development work is happening
    • Has an assigned developer who is currently implementing the solution
    • Should have associated branch/PR in progress

  • Needs Review

    • Implementation is complete and ready for review
    • Pull request is open and requires code review
    • Waiting on reviewers to provide feedback

  • Approved

    • Implementation has received all necessary approvals
    • Pull request is ready to be merged
    • If there are unrelated CI blockers preventing the merge, status can be changed to "Blocked"

  • Blocked

    • Cannot proceed due to external dependency or blocker
    • Clearly documented what is blocking progress
    • Requires intervention to unblock

  • Done

    • Work is complete and merged to main branch
    • All acceptance criteria met
    • Issue can be closed

Pull Request Status

Pull requests can be in one of five states: "In Progress", "Needs Review", "Approved", "Blocked", or "Done". It is not necessary to keep the issue status in sync with the PR status. For example, an issue can simply remain in the "In Progress" status while a PR is going through the review cycle.

When to Create Issues

All PRs should be associated with an issue. Exceptions include trivial PRs where creating the issue would take longer than creating the PR itself (e.g., fixing a typo). It is perfectly acceptable to create an issue after creating the PR.

Issue Organization

We use three main types of issue organization:

  1. Parent/Sub-issues

    • Primary method for organizing work with clear definition of done
    • Parent tracks progress and provides context; sub-issues can have minimal or empty descriptions
    • Link using GitHub's issue linking interface

  2. Tracker Issues

    • Used for grouping related issues without strict dependencies
    • Helpful for organizing work by theme or area
    • More flexible than parent/sub-issues or epics

  3. Epics

    • Used for large initiatives spanning multiple releases
    • Contains multiple independent pieces of work
    • May involve multiple teams or components
    • Often represents strategic initiatives or major features

Labels Usage

Labels should primarily be used for:

  • Component identification (e.g., "knn", "svm", "dask")
  • Issue type (e.g., "bug", "enhancement", "task")

Avoid using labels for work organization - use the issue organization methods above instead.

Issue Triage Process

Core Responsibilities

The project lead is responsible for:

  1. Processing new issues within 24 hours
  2. Reviewing updated issues for status changes
  3. Ensuring issues are actionable and properly categorized
  4. Escalating complex issues to the right team members

The issue triage responsibility can be delegated to other team members, typically on a weekly rotation basis.

Initial Issue Assessment

  1. Initial Assessment

    • Check if the issue is already resolved or invalid
    • Look for duplicates using search
    • Close immediately if resolved/invalid/duplicate with a message politely stating the reason

  2. Issue Type Classification

    • Bug: Something not working as expected
      • Examples: Crashes, incorrect results, performance regressions, CI failures, etc.
    • Enhancement: User-facing improvements
      • Examples: New features, performance improvement
    • Task: Everything else
      • Essentially anything else that is actionable, but not clearly a bug or enhancement.

When in doubt classify as Task.

  1. Title and Description Review

    • Make titles descriptive and specific
    • Do not add any prefixes (they are redundant with issue type) except for "Proposal:"
    • Examples:
      • Bad: "knn not working"
      • Good: "KNN: Incorrect results with large k values"
      • Bad: "add weight knn classification?"
      • Good: "Proposal: Add support for weighted KNN classification"
      • Bad: "need help with mgpu knn training (dask)"
      • Good: "How to configure KneighborsClassifier for multi-GPU training with dask"

  2. Requester Classification

    • Set the "Requester" field for all feature requests with one of the following values:
      • Partner/Customer: Request from a partner or customer
      • Internal: Request originated within NVIDIA but outside the team
      • External: Request from outside NVIDIA with no formal relationship
    • In doubt, leave it empty.
    • In case of multiple matches, select the highest one in the list above (Partner/Customer > Internal > External)
    • This classification helps prioritize and track the source of feature requests

  3. Making Issues Actionable

    For Bug Reports:

    • Ensure reproduction steps are clear and complete
    • Verify environment information is provided
    • Request specific examples if needed
    • Try to reproduce if feasible

    For Enhancements:

    • Ensure the proposal is concrete and specific
    • Check that the use case is clearly explained
    • Verify scope is reasonably defined

    For Tasks:

    • Ensure question/request is clearly stated
    • Gather necessary context for answering
    • Answer the question or try to find someone who can

  4. Initial Response

    • Comment on the issue to acknowledge it
    • Express appreciation for the report/question
    • This is especially important for user questions or requests
    • Subscribing ensures you'll be notified of any updates

Ongoing Issue Management

  1. Label Management

    • Remove "? - Needs Triage" once triaged
    • Add "information-requested" if more information needed
    • Apply any other relevant labels (component, etc.)

  2. Status Updates

    • Monitor issue progress and update status as needed
    • Close if resolved or no longer relevant
    • Reopen if new information makes issue relevant again
    • Update labels if issue type has changed
    • Remove "information-requested" label if now actionable

  3. Progress Monitoring

    • Ensure discussions are productive
    • Unblock stalled conversations
    • Ping relevant team members if needed

Escalation Guidelines

Escalate issues when:

  • They are urgent (affecting multiple users/blocking work)
  • They require specific expertise
  • They have broad architectural implications
  • They involve multiple components/teams

Methods of escalation:

  1. Tag relevant experts directly in the issue
  2. Share in team slack channel
  3. Add to team meeting agenda if needed

Daily Workflow for weekly triage manager

The triage manager is responsible for issues in two states:

  • "Needs Triage": Initial review and categorization
  • "Needs More Information": Following up on information requests

Issues in other states should still be monitored if you're subscribed to them, but they don't require triage action.

Daily Process

  1. Review "Needs Triage" issues on the cuML Triage board:

    • Assess each issue for validity and completeness
    • Move to "Todo" if immediately actionable
    • Move to "Needs More Information" if additional details are required

  2. Review "Needs More Information" issues:

    • Request additional information if still needed
    • Escalate to team members if necessary
    • Move to "Todo" once actionable

  3. Monitor other subscribed issues:

    • Respond to any updates or questions
    • Help unblock issues if possible
    • Escalate to appropriate team members when needed

Best Practices

  • Be polite and professional in all interactions
  • Ask clarifying questions rather than making assumptions
  • Set clear expectations about response times
  • Document decisions and reasoning
  • Link related issues and discussions
  • Update issue titles to be more descriptive if needed

Remember: The goal is to make issues actionable, not to solve them immediately. Focus on categorization, clarity, and proper routing rather than immediate resolution.

Status Automations

Current Automations

  • New issues, sub-issues, and PRs are automatically added to the project
  • New issues are automatically set to "Needs Triage"
  • When a PR is merged, both the PR and its associated issue are set to "Done"
  • The Release field is automatically updated for PRs and their associated issues based on the target branch
  • PR status is set to "In Progress" when changes are requested
  • PR status is set to "Approved" when approved
  • Issues are automatically closed when set to "Done"
  • The PR assignee is set to the PR author upon first creation

Future Automations

Some automations under consideration:

  • Sync PR "priority" with issue "priority"
  • Sync "Needs More Information" status with the "information-requested" label
  • Sync "Blocked" status with the "blocked" label
  • Set "Todo" status for new issues from contributors
  • Set "In Progress" status when a PR is linked to an issue

Clone this wiki locally