Lines Matching refs:to
1 # Contributing to Tonic
3 :balloon: Thanks for your help improving the project! We are so happy to have
6 There are opportunities to contribute to `tonic` at any level. It doesn't
13 It should be considered a map to help you navigate the process.
29 The `tonic` project adheres to the [Rust Code of Conduct][coc]. This describes
40 hyperium/tonic [issue tracker][issues] is the way to report it.
42 2. By helping to triage the issue: This can be done by providing
44 suggestions on how to address the issue, or ensuring that the issue is tagged
47 3. By helping to resolve the issue: Typically this is done either in the form of
52 **Anybody can participate in any stage of contribution**. We urge you to
70 template to the best of your ability. Do not worry if you cannot answer every
73 The two most important pieces of information we need in order to properly
75 test case we can use to recreate the problem on our own. If we cannot recreate
76 the issue, it becomes impossible for us to fix.
78 In order to rule out the possibility of bugs introduced by userland code, test
79 cases should be limited, as much as possible, to using only Tokio APIs.
81 See [How to create a Minimal, Complete, and Verifiable example][mcve].
88 Once an issue has been opened, it is not uncommon for there to be discussion
97 Contributors are encouraged to help one another make forward progress as much as
98 possible, empowering one another to solve issues collaboratively. If you choose
99 to comment on an issue that you feel either is not a problem that needs to be
102 to be convinced that you may be wrong. By doing so, we can often reach the
108 process for opening and reviewing a Pull Request is similar to that of opening
115 Pull Requests are the way concrete changes are made to the code, documentation,
120 usually a good idea to first open an issue describing the change to solicit
126 If the change being proposed alters code (as opposed to only documentation for
127 example), it is either adding new functionality to a crate or it is fixing
129 include one or more tests to ensure that the crate does not regress in the future.
130 There are two ways to write tests: integration tests and documentation tests
137 `tonic` utilities available to use in tests, no matter the crate being
140 The best strategy for writing a new integration test is to look at existing
145 Ideally, every API has at least one [documentation test] that demonstrates how to
149 The trick to documentation tests is striking a balance between being succinct
150 for a reader to understand and actually testing the API.
175 /// // Wrap the future with a `Timeout` set to expire in 10 milliseconds.
186 They are only there to get the test to run. The `block_on_all` function is the
187 easiest way to execute a future from a test.
203 /// // Wrap the future with a `Timeout` set to expire in 10 milliseconds.
211 When making changes to `tonic-build` that affects the generated code you will
212 need to ensure that each of the sub crates gets updated as well. Each of the sub
222 It is a recommended best practice to keep your changes as logically grouped as
223 possible within individual commits. There is no limit to the number of commits
224 any single Pull Request may have, and many contributors find it easier to review
242 the words that refer to code, like function/variable names
253 4. If your patch fixes an open issue, you can add a reference to it at the end
284 [template] that should be filled out. Please try to do your best at filling out
285 the details, but feel free to skip parts if you're not sure what to put.
291 You will probably get feedback or requests for changes to your Pull Request.
295 in order to evaluate whether the changes are correct and necessary.
298 Keep an eye out for comments from code owners to provide guidance on conflicting
306 In most cases, **do not squash commits that you add to your Pull Request during
308 squashed into one commit per logical change. Metadata will be added to the
309 commit message (including links to the Pull Request, links to relevant issues,
315 **Any Tokio and Hyperium community member is welcome to review any pull request**.
317 All Tokio contributors who choose to review and provide feedback on Pull
318 Requests have a responsibility to both the project and the individual making the
320 towards improving the contribution as opposed to simply blocking it. If there
322 expect to be able to block a Pull Request from advancing simply because you say
323 "No" without giving an explanation. Be open to having your mind changed. Be open
324 to working with the contributor to make the Pull Request better.
327 reviewers are strictly counter to the Code of Conduct.
329 When reviewing a Pull Request, the primary goals are for the codebase to improve
330 and for the person submitting the request to succeed. **Even if a Pull Request
333 contributor is an opportunity to grow the community.
339 It is tempting to micro-optimize and make everything about relative performance,
340 perfect grammar, or exact style matches. Do not succumb to that temptation.
346 3. Are there clear bugs or larger scale issues that need attending to?
350 Note that only **incremental** improvement is needed to land a PR. This means
351 that the PR does not need to be perfect, only better than the status quo. Follow
352 up PRs may be opened to continue iterating.
355 assume that the submitter already knows how to add a test or run a benchmark**.
358 change over time. The first impression you give to a new contributor never does.
360 Nits (requests for small changes that are not essential) are fine, but try to
363 the contributor to learn a bit more about the project.
365 It is always good to clearly indicate nits when you comment: e.g.
366 `Nit: change foo() to bar(). But this is not blocking.`
369 commits or if they proved to be mistaken, please, [hide them][hiding-a-comment]
370 with the appropriate reason to keep the conversation flow concise and relevant.
377 just not want to have anything to do with `tonic` ever again. The goal is
382 If a Pull Request appears to be abandoned or stalled, it is polite to first
383 check with the contributor to see if they intend to continue the work before
385 left). When doing so, it is courteous to give the original contributor credit
398 each other, releasing new versions to crates.io can involve some complexities.
401 1. First you must pick the correct version to release, if there are breaking
402 changes make sure to select a semver compatible version bump.
404 2. In general, tonic tries to keep all crates at the same version to make it
405 easy to release and figure out what sub crates you need that will work with
413 3. Once all the crate versions have been updated its time to update the
414 changelog. Tonic uses `conventional-changelog` and it's cli to generate the
422 to add the version and tag to the title and edit any changelog entries. You