mirror of
https://github.com/tokio-rs/tokio.git
synced 2026-08-13 00:00:24 +02:00
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
## Contributing in Issues
|
|
|
|
For any issue, there are fundamentally three ways an individual can contribute:
|
|
|
|
1. By opening the issue for discussion: For instance, if you believe that you
|
|
have discovered a bug in Tokio, creating a new issue in [the tokio-rs/tokio
|
|
issue tracker][issue] is the way to report it.
|
|
|
|
2. By helping to triage the issue: This can be done by providing
|
|
supporting details (a test case that demonstrates a bug), providing
|
|
suggestions on how to address the issue, or ensuring that the issue is tagged
|
|
correctly.
|
|
|
|
3. By helping to resolve the issue: Typically this is done either in the form of
|
|
demonstrating that the issue reported is not a problem after all, or more
|
|
often, by opening a Pull Request that changes some bit of something in
|
|
Tokio in a concrete and reviewable manner.
|
|
|
|
[issue]: https://github.com/tokio-rs/tokio/issues
|
|
|
|
**Anybody can participate in any stage of contribution**. We urge you to
|
|
participate in the discussion around bugs and participate in reviewing PRs.
|
|
|
|
### Asking for General Help
|
|
|
|
If you have reviewed existing documentation and still have questions or are
|
|
having problems, you can [open a discussion] asking for help.
|
|
|
|
In exchange for receiving help, we ask that you contribute back a documentation
|
|
PR that helps others avoid the problems that you encountered.
|
|
|
|
[open a discussion]: https://github.com/tokio-rs/tokio/discussions/new/choose
|
|
|
|
### Submitting a Bug Report
|
|
|
|
When opening a new issue in the Tokio issue tracker, you will be presented
|
|
with a basic template that should be filled in. If you believe that you have
|
|
uncovered a bug, please fill out this form, following the template to the best
|
|
of your ability. Do not worry if you cannot answer every detail, just fill in
|
|
what you can.
|
|
|
|
The two most important pieces of information we need in order to properly
|
|
evaluate the report is a description of the behavior you are seeing and a simple
|
|
test case we can use to recreate the problem on our own. If we cannot recreate
|
|
the issue, it becomes impossible for us to fix.
|
|
|
|
In order to rule out the possibility of bugs introduced by userland code, test
|
|
cases should be limited, as much as possible, to using only Tokio APIs.
|
|
|
|
See [How to create a Minimal, Complete, and Verifiable example][mcve].
|
|
|
|
[mcve]: https://stackoverflow.com/help/mcve
|
|
|
|
### Triaging a Bug Report
|
|
|
|
Once an issue has been opened, it is not uncommon 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.
|
|
|
|
Short, clipped responses—that provide neither additional context nor supporting
|
|
detail—are not helpful or professional. To many, such responses are simply
|
|
annoying and unfriendly.
|
|
|
|
Contributors are encouraged to help one another make forward progress as much as
|
|
possible, empowering one another to solve issues collaboratively. If you choose
|
|
to comment on an issue that you feel either is not a problem that needs to be
|
|
fixed, or if you encounter information in an issue that you feel is incorrect,
|
|
explain why you feel that way with additional supporting context, and be willing
|
|
to be convinced that you may be wrong. By doing so, we can often reach the
|
|
correct outcome much faster.
|
|
|
|
### Resolving a Bug Report
|
|
|
|
In the majority of cases, issues are resolved by opening a Pull Request. The
|
|
process for opening and reviewing a Pull Request is similar to that of opening
|
|
and triaging issues, but carries with it a necessary review and approval
|
|
workflow that ensures that the proposed changes meet the minimal quality and
|
|
functional guidelines of the Tokio project.
|