Skip to content

Triage Process

Jump to bottom
Simon Adorf edited this page May 6, 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 and ready for development
    • Has all necessary information and clear acceptance criteria
    • Applied manually by project lead

  • 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". The PR status should be kept in sync with the corresponding issue's status (e.g., if a pr is in status "Needs Review", its issue should also be "Needs Review"). This synchronization will be automated in the future.

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.

Sub-issues

Create sub-issues when:

  • A pull request only addresses part of a larger issue and you need to track progress towards the parent issue
  • The work is a clear subset of a larger task that needs to be broken down
  • Multiple developers need to work on different parts of a larger feature

Sub-issues should be:

  • Linked to the parent issue using GitHub's issue linking interface
  • Given short but descriptive titles that clearly indicate their scope
  • Brief in description - one or two sentences is usually sufficient
  • Used primarily to track progress and dependencies for the parent issue

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: Request for new functionality
      • Examples: New features, API changes, performance improvement
    • Task: User support requests / benchmark requests
      • Essentially anything that is actionable, but does not require a change to the code or docs.
      • When in doubt between Bug/Task, classify as Bug

  3. 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

  4. 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"

  5. 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

  6. 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

To effectively manage your issue management workload, follow these three steps:

  1. Triage each newly created issue with a maximum lookback of 1 week.

    You can use the following search filter to identify these issues:

    is:issue is:open label:"? - Needs Triage" created:>@today-1w sorted:created-asc

    This list should be empty by the end of each day.

  2. Review newly updated issues with a maximum lookback of 1 week:

    is:issue is:open updated:>@today-1w sort:updated-desc

    Review this list at least once a day.

  3. Respond to any other issue that you are subscribed to.

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

  • Issue status "Needs Triage" is automatically applied to all new issues
  • Issue status "Done" is automatically applied when an issue is closed
  • PR status "Done" is automatically applied when a PR is merged

Future Automations

  • Issue status "Needs Triage" will be automatically applied to all new issues from external sources
  • Issue status "Needs More Information" will be automatically applied when the "information-requested" label is applied
  • Issue status "Todo" will be automatically applied to all new issues from internal sources
  • Issue status "In Progress" will be automatically applied when a PR is linked
  • Issue status "Needs Review" will be automatically applied when a PR is requesting reviews
  • Issue status "Blocked" will be automatically applied when the "blocked" label is applied
  • PR status "In Progress" will be automatically applied when:
    • PR is opened or updated
    • PR is moved back from "Needs Review"
  • PR status "Needs Review" will be automatically applied when PR is marked ready for review
  • PR status "Blocked" will be automatically applied when the "blocked" label is applied

Clone this wiki locally