Skip to content

docs(dev): create PR triage chapter - #15404

Draft
joshtrichards wants to merge 3 commits into
masterfrom
jtr/docs-dev-PR-triage
Draft

docs(dev): create PR triage chapter#15404
joshtrichards wants to merge 3 commits into
masterfrom
jtr/docs-dev-PR-triage

Conversation

@joshtrichards

@joshtrichards joshtrichards commented Aug 2, 2026

Copy link
Copy Markdown
Member

☑️ Resolves

WIP/Early days yet, but I think we can do better at triaging our PR quick with a minimal label scheme:

⚠️ risk: low                  green
⚠️ risk: medium               amber
⚠️ risk: high                 orange
⚠️ risk: critical             red

⏱️ review-effort: quick       blue
⏱️ review-effort: focused     dark blue
⏱️ review-effort: thorough    purple
⏱️ review-effort: deep        dark purple

The labels can be applied by the author or a triager.

This is an early draft documenting the concept.

Real-world example (proof of concept on a real PR): nextcloud/server#62772


As the number and variety of pull requests grows, prospective reviewers need a quick way to judge whether a change is suitable for them to review and how much attention it may require.

This proposal introduces a lightweight, standardized approach to pull request triage using a small set of descriptive labels and an optional summary in the pull request body. The intent is not to predict review time precisely or replace reviewer judgment. Instead, the approach should provide a common vocabulary for communicating the characteristics that matter most during reviewer selection.

To avoid label fatigue, only the most actionable labels should be prominent by default.

🖼️ Screenshots

✅ Checklist

  • I have built the documentation locally and reviewed the output
  • Screenshots are included for visual changes
  • I have not moved or renamed pages (or added a redirect if I did)
  • I have run codespell or similar and addressed any spelling issues

Signed-off-by: Josh <josh.t.richards@gmail.com>
…chapter

Signed-off-by: Josh <josh.t.richards@gmail.com>
@joshtrichards joshtrichards changed the title Jtr/docs dev pr triage docs(dev): create PR triage chapter Aug 2, 2026
Signed-off-by: Josh <josh.t.richards@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant