Issues

The issue tracker 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 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. 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. 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.

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.