Skip to content

Rewrite docs/TriageProcess.md to be timeless and more comprehensive#66566

Open
danroth27 wants to merge 6 commits intodotnet:mainfrom
danroth27:docs/triage-process-rewrite
Open

Rewrite docs/TriageProcess.md to be timeless and more comprehensive#66566
danroth27 wants to merge 6 commits intodotnet:mainfrom
danroth27:docs/triage-process-rewrite

Conversation

@danroth27
Copy link
Copy Markdown
Member

@danroth27 danroth27 commented May 1, 2026

Rewrites docs/TriageProcess.md to be tighter, more comprehensive, and version-neutral. Also fills a small documentation gap in docs/IssueManagementPolicies.md for the Needs: Repro label.

What changed

Trimmed

  • Removed the "managing a popular GitHub repo is hard" preamble and the explicit "Goals" section.
  • Replaced wordy per-section narratives with a tight outcome table and per-type checklists.
  • Removed the externally-hosted PNG diagram. (A Mermaid flowchart was tried during review but dropped — the prose flow is sufficient.)

Made timeless

  • Removed every reference to specific .NET versions (e.g. .NET 11 Planning).
  • Uses role-based phrases instead: servicing milestone (N.0.x), current release milestone (N.0-previewX), current-release planning milestone (.NET N Planning), Backlog. The doc no longer needs editing each release.

Filled gaps the previous doc missed

  • Explicit list of all triage outcomes including servicing (the previous doc never mentioned it).
  • Explicit impact-assessment criteria: regression-in-supported-release, severity, reach, 👍/comments, workaround availability.
  • "What a good bug report contains" — useful for the community-facing audience.
  • Explicit handling for wrong-repo issues, security vulnerabilities, investigations, and documentation tasks.
  • Documents the Needs: Repro label automation in IssueManagementPolicies.md.

Cross-document hygiene

  • Servicing bar, repro requirements, Needs: * automation, and release scoping all defer to the existing Servicing.md / repro.md / IssueManagementPolicies.md / ReleasePlanning.md docs rather than restating them.

Audiences

The rewrite makes both audiences explicit at the top:

  • Community members filing issues — what to expect.
  • Engineers joining the team — how to triage consistently.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions Bot added the needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically label May 1, 2026
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
Comment thread docs/TriageProcess.md Outdated
- Drop the Mermaid diagram (too complicated)

- Restructure outcomes around actual milestones (N.0.x, .NET N Planning, Backlog)

- Switch from type labels to GitHub issue type field (Bug/Feature/Task/Epic)

- Reference Servicing.md, IssueManagementPolicies.md, repro.md instead of duplicating

- Use Dan's verbatim text for investigations, feature priorities, docs, wrong-repo

- Use Needs: Repro label; clarify 'milestone is intent, not commitment'

- Drop 'what we triage' framing; set realistic response-time expectation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@danroth27
Copy link
Copy Markdown
Member Author

Pushed 041a869 addressing review feedback. Summary of changes:

  • Removed the Mermaid diagram entirely (too complicated).
  • Dropped "weekly" — now says we review untriaged issues "regularly".
  • Reframed "milestone" language — now "milestone reflects current intent, not a guarantee" (per @Youssef1313 — "planning to work on it").
  • Restructured outcomes table around actual milestones: N.0.x servicing, .NET N Planning (with note that issues are scheduled into N.0-previewX during planning), and Backlog.
  • Clarified "Closed" outcome with explicit list (duplicate, by-design, won't fix, can't repro, already fixed) — replaces vague "invalid".
  • Switched to GitHub Issue Type field (Bug/Feature/Task/Epic) instead of bug/enhancement/task labels.
  • Replaced inline servicing-bar and Needs: Author Feedback content with links to Servicing.md and IssueManagementPolicies.md to avoid duplication.
  • Repros now point to docs/repro.md and use the Needs: Repro label.
  • Investigations, Documentation requests, Wrong repo, and Feature priorities sections use your suggested wording verbatim.
  • Dropped "What we triage" framing; opens with realistic response-time expectation.
  • References section now points at IssueManagementPolicies.md, repro.md, ReleasePlanning.md, and Servicing.md.

On the meta-comment about reviewing related docs together: I leaned hard into linking out rather than restating, so this doc is now mostly triage-specific logic — servicing bar lives in Servicing.md, automation lives in IssueManagementPolicies.md, repro guidance lives in repro.md, release scoping lives in ReleasePlanning.md. Happy to consolidate further if you spot remaining overlap.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Comment thread docs/TriageProcess.md Outdated
danroth27 and others added 2 commits May 1, 2026 13:48
… note, area-* label, expand Epic

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@danroth27 danroth27 marked this pull request as ready for review May 1, 2026 21:02
Copilot AI review requested due to automatic review settings May 1, 2026 21:02
@danroth27 danroth27 requested review from lewing and tkapin May 1, 2026 21:03
@danroth27 danroth27 requested a review from SamMonoRT May 1, 2026 21:03
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Rewrites docs/TriageProcess.md to describe the issue triage workflow for dotnet/aspnetcore in a more version-neutral, outcome-oriented way for both community reporters and new team engineers.

Changes:

  • Replaces the previous narrative triage description with explicit triage outcomes and per-issue-type guidance (Bug/Feature/Task/Epic).
  • Adds impact/severity assessment criteria for bugs and clarifies repo transfer behavior for wrong-repo issues.
  • Updates references to related repo documentation (Issue Management Policies, repro guide, release planning, servicing).

Comment thread docs/TriageProcess.md
Comment thread docs/TriageProcess.md
Comment thread docs/TriageProcess.md
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants