Skip to content

Commit

Permalink
docs(contrib): add guide for Triaging Issues
Browse files Browse the repository at this point in the history
  • Loading branch information
seanmonstar committed May 25, 2022
1 parent 775fac1 commit 4678be9
Showing 1 changed file with 64 additions and 0 deletions.
64 changes: 64 additions & 0 deletions docs/ISSUES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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".
Expand Down Expand Up @@ -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

0 comments on commit 4678be9

Please sign in to comment.