114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# Issues
|
|
|
|
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 gathered, 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 succinct action to
|
|
be taken. For example, a question about an non-existent 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".
|
|
|
|
### Area
|
|
|
|
The area labels describe what part of hyper is relevant.
|
|
|
|
- **A-body**: streaming request and response bodies.
|
|
- **A-client**: the HTTP client.
|
|
- **A-dependencies**: library dependencies.
|
|
- **A-docs**: documentation.
|
|
- **A-error**: error reporting and types.
|
|
- **A-ffi**: the C API.
|
|
- **A-http1**: the HTTP/1 specifics.
|
|
- **A-http2**: the HTTP/2 specifics.
|
|
- **A-server**: the HTTP server.
|
|
- **A-tests**: the unit and integration tests.
|
|
|
|
### Blocked
|
|
|
|
These labels indicate an issue is "blocked" for some reason.
|
|
|
|
- **B-breaking-change**: a breaking change that is waiting for the next semver-compatible release.
|
|
- **B-rfc**: request for comments. More discussion is needed to explore the design.
|
|
- **B-upstream**: waiting on something in a dependency or the compiler.
|
|
|
|
### Effort
|
|
|
|
The effort labels are a best-guess at roughly how much effort and knowledge of hyper is needed to accomplish the task.
|
|
|
|
- **E-easy**: a great starting point for a new contributor.
|
|
- **E-medium**: some knowledge of how hyper internals work would be useful.
|
|
- **E-hard**: likely requires a deeper understanding of how hyper internals work.
|
|
|
|
### Severity
|
|
|
|
The severity marks how _severe_ the issue is. Note this isn't "importance" or "priority".
|
|
|
|
- **S-bug**: something is wrong, this is bad!
|
|
- **S-feature**: this is a new feature request, adding something new.
|
|
- **S-performance**: make existing working code go faster.
|
|
- **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
|