diff --git a/docs/ISSUES.md b/docs/ISSUES.md index 403143bd..9f36a910 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -2,6 +2,68 @@ The [issue tracker][issues] for hyper is where we track all features, bugs, and discuss proposals. +## Triaging + +Once an issue has been opened, it is normal for there to be discussion +around it. Some contributors may have differing opinions about the issue, +including whether the behavior being seen is a bug or a feature. This +discussion is part of the process and should be kept focused, helpful, and +professional. + +The objective of helping with triaging issues is to help reduce the issue +backlog and keep the issue tracker healthy, while enabling newcomers another +meaningful way to get engaged and contribute. + +### Acknowledge + +Acknowledge the human. This is meant actively, such as giving a welcome, or +thanks for a detailed report, or any other greeting that makes the person feel +that their contribution (issues are contributions!) is valued. It also is meant +to be internalized, and be sure to always [treat the person kindly][COC] +throughout the rest of the steps of triaging. + +### Ask for more info + +Frequently, we need more information than was originally provided to fully +evaluate an issue. + +If it is a bug report, ask follow up questions that help us get a [minimum +reproducible example][MRE]. This may take several round-trip questions. Once +all the details are gathered, it may be helpful to edit the original issue text +to include them all. + +### Categorize + +Once enough information has been gathererd, the issue should be categorized +with [labels][#labels]. Ideally, most issues should be labelled with an area, +effort, and severity. An issue _can_ have multiple areas, pick what fits. There +should be only one severity, and the descriptions of each should help to pick +the right one. The hardest label to select is "effort". If after reading the +descriptions of each effort level, you're still unsure, you can ping a +maintainer to pick one. + +### Adjust the title + +An optional step when triaging is to adjust the title once more information is +known. Sometimes an issue starts as a question, and through discussion, it +turns out to be a feature request, or a bug report. In those cases, the title +should be changed from a question, and the title should be a succict action to +be taken. For example, a question about an non-existant configuration option +may be reworded to "Add option to Client to do Zed". + +### Mentoring + +The last part of triaging is to try to make the issue a learning experience. +After a discussion with the reporter, it would be good to ask if they are now +interested in submitting the change described in the issue. + +Otherwise, it would be best to leave the issue with a series of steps for +anyone else to try to write the change. That could be pointing out that a +design proposal is needed, addressing certain points. Or, if the required +changes are mostly know, a list of links to modules and functions where code +needs to be changed, and to what. That way we mentor newcomers to become +successful contributors of new [pull requests][PRs]. + ## Labels Issues are organized with a set of labels. Most labels follow a system of being prefixed by a "type". @@ -47,3 +109,5 @@ The severity marks how _severe_ the issue is. Note this isn't "importance" or "p - **S-refactor**: improve internal code to help readability and maintenance. [issues]: https://github.com/hyperium/hyper/issues +[COC]: ./CODE_OF_CONDUCT.md +[PRs]: ./PULL_REQUESTS.md