How to triage issues¶
To triage is to determine the priorities in a situation. In the context of software engineering, issue triage means to ensure that every issue contains enough information to be resolved by a developer. This involves adding enough information to clarify a ~Bug or ~"Feature Request", accurately labelling issues so that they can be searched and filtered, and assigning them to milestones and developers.
In Beautiful Canoe, most issue triage is done by the CTO and @bc-bot, but any member of the company can triage issues. As a minimum, every developer should take responsibility for triaging issues that they have raised.
Levels of triage¶
We define three levels of triage:
Level 1 (triage has been started):
Level 2 (triage is partial):
- Has steps to reproduce and has been ~Confirmed, if the type is ~Bug
- Has a clear description and business case, and criteria for completion and QA testing, if the type is ~"Feature Request".
Level 3 (triage is complete):
- Has a workflow label.
- Has a milestone set.
- Has a developer assigned.
Initial triage involves (at least) adding appropriate labels, so that un-triaged issues can be discovered by searching for issues without any labels.
Some questions to keep in mind:
- Do you understand what the issue is describing?
- What labels apply?
- How critical does it seem?
- Has the issue been raised specifically by the client (in which case, it should have higher priority)?
- Would the ~"Security Vulnerability" label be appropriate?
- Should it be made confidential? ~"Security Vulnerability" issues should always be confidential.
Apply each label that seems appropriate.
If the issue seems unclear, or you aren't sure which labels to apply, ask the person who raised the issue to clarify. If that person who raised the issue has left the company, check with the CTO. Make sure you check GitLab regularly for replies to your discussion comments.
Check for ~Duplicate issues. Searching for some keywords in the issue should give you a list possible duplicates to consider. Check both open and closed issues. If an issue has been duplicated, mark one of the issues with ~"Wont Fix", leave a comment on it such as Closing as duplicate of #N and close it. Before you close, make sure that any useful information in the closed issue is left as a comment in the issue you leave open.
Consider whether the issue is still valid.
Especially for older issues, a ~Bug may have been fixed since it was reported, or a ~"Feature Request" may have already been implemented.
You might want to search through commit messages in the
git log, or a development, staging or production deployment of the code if you are unsure.
Labels relating to milestones, such as ~Missed:2019.1, are added automatically by @bc-bot -- please do not add them automatically.
Issue triage best practices¶
Take ownership of issues you've opened¶
Sort issues by Author: your username and close any issues which you know have been fixed or have become irrelevant for other reasons. Label them if they're not labelled already. Make sure that you reply to any comments on your issues.
- issues marked ~"Security Vulnerability" should be marked ~Priority:High.
- issues that affect the accessibility of a product should be marked ~Priority:High, because they prevent groups of users using the product.
- issues that have some user experience component should not be marked ~Priority:Low.
- issues marked ~Documentation should not be marked ~Priority:Low, and you should consider documentation to be equally important as code.
Good first issues¶
Some issues have low priority but are easy to resolve. These should be marked as ~"Good First Issue", to encourage developers who are new to the project to pick them up.
If you notice a common pattern amongst various issues, feel free to suggest adding a new label the relevant Slack channel.