A proposal for Issues, Discussions, and Triage in Unit

[callahad]

Hi folks, I'd like to propose a system for how we manage GitHub Issues and GitHub Discussions. Provided there are no objections, I'll implement it on Wednesday, 31st January.

If you want more on this topic, I really like Avery Pennarun's blog post: An epic treatise on scheduling, bug tracking, and triage. I've also been influenced by Mozilla's Bug Handling guidelines, and the Rust Project's Issue Triage process.

High Level Overview

• Issues as work to be done.
• Discussions are for everything else.

"Work to be done" means that for each issue it must be clear what the next step is, when we'll know we're done, and that we want it done. Issues are actionable, scoped, and aligned with our vision for Unit.

Discussions are used for user support, feature requests, process questions, etc.

Examples

• CI failure? Open an issue.
• Bug report? Diagnosing it is an issue. Fixing it might not be.
• Feature request? Not an issue until we agree that we want to take Unit in that direction.
• Support question? Not an issue, but could lead to new issues being filed.

Issue Triage

Triage assesses incoming issues against our criteria above: Is it actionable? Does it have a definition of done? Do we want to do it? If not, it's the triager's responsibility to determine these things.

For many people, their first interaction with the Unit team will be through filing an issue. Ensuring that someone on our side looks at and responds to every incoming issue is key to building an engaged, participatory community.

Issue Labels

We should have several categories of labels, generally denoted by a shared prefix.

Note

I am intentionally omitting labels for Severity and Priority; we're small enough that severity can be handled informally within the team, and Priority will be expressed via GitHub Milestones and/or Projects.

Type: Every issue is assigned a type.

• T-Defect — Bugs, crashes, hangs, vulnerabilities, or other reported problems.
• T-Enhancement — New features, changes in functionality, performance boosts, user-facing improvements.
• T-Other — Epics / Meta-bugs, refactoring, enabling or disabling functionality, other engineering tasks.

Language: Issues related to specific language modules are labeled as such.

• L-Go, L-Java, L-JavaScript, L-PHP, L-Perl, L-Python, L-Ruby, L-WebAssembly
• L-Other — Binary embeddings with libunit

Exception: Special flags for issues and pull requests.

• X-Needs-Discussion — The team needs to discuss this before further action is taken.
• X-Needs-Info — This issue is blocked pending further information from the reporter.
• X-Release-Blocker — Issues which must be resolved before making a release.

Issues are considered triaged when they have a Type and/or an Exception label.

Assigning Issues

The assignee owns the issue.

Only assign yourself to issues that you are actively committed to working on.

GitHub Discussions

We should have four categories for discussions:

• 💬 General (open discussion)
• 🖋️ Governance (for topics like these; only maintainers can start posts here)
• 💡 Ideas (open discussion)
• 🆘 Support (Q&A format with option of marking a best answer)

I suggest we fold our current 🙌 Show and Tell category into 💬 General.

[tippexs]

I like this from rust

When an issue is opened, it gets the needs-triage label. This ensures that every issue gets an initial look and that no issue is ignored, or that when it is ignored, it is at least visibly ignored by still having the label.

needs-triage is an initial checkpoint. The effort needed to get an issue past the label should be small.

https://forge.rust-lang.org/release/issue-triaging.html#initial-triaging

This would replace our needs investigation label.

[callahad]

Yeah, the automatic needs-triage works great for Rust. On smaller teams, I've had better luck with an implicit / intrinsic definition of "needs triage": If it does not have a T-* label, it needs triage.

...And then we make reviewing that query and X-Needs-Discussion a standard part of our recurring standups.

As for our existing labels like needs investigation, the way I'd propose implementing this is renaming all current labels with a z- prefix (z-bug, z-php, etc.) and then as we go through and re-triage everything, re-label issues with the "new" T-/L-/X- labels. That way we don't lose context during re-triage, and we maintain a clear divide between old and new labeling regimes.

[callahad]

This has been implemented; the Show and Tell categories was kept.