Skip to content

Commit

Permalink
docs: fix typos and markdown lints (#369)
Browse files Browse the repository at this point in the history 
Found via these commands:

    codespell .
    markdownlint *.md --disable MD013
  • Loading branch information
@kianmeng @hawkw
kianmeng authored and hawkw committed Sep 29, 2023
1 parent 0a6012b commit 8e3c6c5
Show file tree
Hide file tree
Showing 4 changed files with 57 additions and 47 deletions.
7 changes: 5 additions & 2 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# Code of Conduct

The Tokio project adheres to the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct). This describes the minimum behavior expected from all contributors.
The Tokio project adheres to the
[Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
This describes the minimum behavior expected from all contributors.

## Enforcement

Instances of violations of the Code of Conduct can be reported by contacting the project team at [moderation@tokio.rs](mailto:moderation@tokio.rs).
Instances of violations of the Code of Conduct can be reported by contacting
the project team at [moderation@tokio.rs](mailto:moderation@tokio.rs).
63 changes: 31 additions & 32 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
:balloon: Thanks for your help improving the project! We are so happy to have
you!

There are opportunities to contribute to Tokio at any level. It doesn't matter if
you are just getting started with Rust or are the most weathered expert, we can
use your help.
There are opportunities to contribute to Tokio at any level. It doesn't matter
if you are just getting started with Rust or are the most weathered expert, we
can use your help.

**No contribution is too small and all contributions are valued.**

Expand All @@ -20,8 +20,8 @@ not covered in this guide, please joinus!
## Conduct

The Tokio project adheres to the [Rust Code of Conduct][coc]. This describes
the _minimum_ behavior expected from all contributors. Instances of violations of the
Code of Conduct can be reported by contacting the project team at
the _minimum_ behavior expected from all contributors. Instances of violations
of the Code of Conduct can be reported by contacting the project team at
[moderation@tokio.rs](mailto:moderation@tokio.rs).

[coc]: https://github.com/rust-lang/rust/blob/master/CODE_OF_CONDUCT.md
Expand Down Expand Up @@ -156,7 +156,7 @@ The provided [example application] can be used for testing UI changes:

When opening pull requests that make UI changes, please include one or more
screenshots demonstrating your change! For bug fixes, it is often also useful to
include a screenshot showing the console *prior* to the change, in order to
include a screenshot showing the console _prior_ to the change, in order to
demonstrate the bug that's being fixed.

#### Integration tests
Expand All @@ -178,7 +178,7 @@ for a reader to understand and actually testing the API.
The type level example for `tokio_timer::Timeout` provides a good example of a
documentation test:

```
```rust
/// // import the `timeout` function, usually this is done
/// // with `use tokio::prelude::*`
/// use tokio::prelude::FutureExt;
Expand All @@ -204,7 +204,7 @@ documentation test:
/// # }
```

Given that this is a *type* level documentation test and the primary way users
Given that this is a _type_ level documentation test and the primary way users
of `tokio` will create an instance of `Timeout` is by using
`FutureExt::timeout`, this is how the documentation test is structured.

Expand All @@ -215,7 +215,7 @@ easiest way to execute a future from a test.
If this were a documentation test for the `Timeout::new` function, then the
example would explicitly use `Timeout::new`. For example:

```
```rust
/// use tokio::timer::Timeout;
/// use futures::Future;
/// use futures::sync::oneshot;
Expand Down Expand Up @@ -254,7 +254,7 @@ history**. But also, we use the git commit messages to **generate the
change log**.

Since commits are merged by [squashing](#commit-squashing), these rules are not
required for individual commits to a development branch. However, they *are*
required for individual commits to a development branch. However, they _are_
required for the final squash commit to the `main` branch. Generally, the PR
description and title are used as the commit message for the squash commit.
Therefore, please try to follow these rules when writing the description and
Expand All @@ -266,7 +266,7 @@ Each commit message consists of a **header**, a **body** and a
**footer**. The header has a special format that includes a **type**,
an (optional) **scope** and a **subject**:

```
```sh
<type>(<scope>): <subject>
<BLANK LINE>
<body>
Expand All @@ -284,6 +284,7 @@ which we use to generate changelogs.
[clog]: https://github.com/clog-tool/clog-cli

#### Type

Must be one of the following:

* **feat**: A new feature
Expand Down Expand Up @@ -335,7 +336,6 @@ is also the place to reference GitHub issues that this commit
The last line of commits introducing breaking changes should be in the
form `BREAKING CHANGE: <desc>`


### Opening the Pull Request

Open a new pull request using the GitHub web UI. Please try to follow the
Expand Down Expand Up @@ -388,7 +388,7 @@ does not land, the submitters should come away from the experience feeling like
their effort was not wasted or unappreciated**. Every Pull Request from a new
contributor is an opportunity to grow the community.

### Review a bit at a time.
### Review a bit at a time

Do not overwhelm new contributors.

Expand All @@ -407,7 +407,7 @@ Note that only **incremental** improvement is needed to land a PR. This means
that the PR does not need to be perfect, only better than the status quo. Follow
up PRs may be opened to continue iterating.

When changes are necessary, *request* them, do not *demand* them, and **do not
When changes are necessary, _request_ them, do not _demand_ them, and **do not
assume that the submitter already knows how to add a test or run a benchmark**.

Specific performance optimization techniques, coding styles and conventions
Expand All @@ -427,7 +427,7 @@ with the appropriate reason to keep the conversation flow concise and relevant.

### Be aware of the person behind the code

Be aware that *how* you communicate requests and reviews in your feedback can
Be aware that _how_ you communicate requests and reviews in your feedback can
have a significant impact on the success of the Pull Request. Yes, we may land
a particular change that makes Tokio better, but the individual might just not
want to have anything to do with Tokio ever again. The goal is not just having
Expand All @@ -440,7 +440,7 @@ check with the contributor to see if they intend to continue the work before
checking if they would mind if you took it over (especially if it just has nits
left). When doing so, it is courteous to give the original contributor credit
for the work they started (either by preserving their name and email address in
the commit log, or by using an `Author: ` meta-data tag in the commit.
the commit log, or by using an `Author:` meta-data tag in the commit.

_Adapted from the [Node.js contributing guide][node]_.

Expand All @@ -458,36 +458,35 @@ targeted at maintainers. Most contributors aren't able to set these labels.

The area label describes cross-cutting areas of work on the console project.

- **A-instrumentation**: Related to application instrumentation (such as adding
* **A-instrumentation**: Related to application instrumentation (such as adding
new instrumentation to an async runtime or other library).
- **A-warnings**: Related to warnings displayed in the console CLI. This
* **A-warnings**: Related to warnings displayed in the console CLI. This
includes changes that add new warnings, improve existing warnings, or
improvements to the console's warning system as a whole.
- **A-recording**: Related to recording and playing back console data.
* **A-recording**: Related to recording and playing back console data.

### Crate

The crate label describes what crates in the repository are involved in an issue
or PR.

- **C-api**: Related to the `console-api` crate and/or protobuf definitions.
- **C-console**: Related to the `console` command-line application.
- **C-subscriber**: Related to the `console-subscriber` crate.
* **C-api**: Related to the `console-api` crate and/or protobuf definitions.
* **C-console**: Related to the `console` command-line application.
* **C-subscriber**: Related to the `console-subscriber` crate.

### Effort and calls for participation

The effort label represents a _best guess_ for the approximate amount of effort
that an issue will likely require. These are not always accurate! :)


- **E-easy**: This is relatively easy. These issues are often good for newcomers
* **E-easy**: This is relatively easy. These issues are often good for newcomers
to the project and/or Rust beginners.
- **E-medium**: Medium effort. This issue is expected to be relatively
* **E-medium**: Medium effort. This issue is expected to be relatively
straightforward, but may require a larger amount of work than `E-easy` issues,
or require some design work.
- **E-hard** This either involves very tricky code, is something we don't know
* **E-hard** This either involves very tricky code, is something we don't know
how to solve, or is difficult for some other reason.
- **E-needs-mvce**: This bug is missing a minimal complete and verifiable
* **E-needs-mvce**: This bug is missing a minimal complete and verifiable
example.

The "E-" prefix is the same as used in the Rust compiler repository. Some
Expand All @@ -499,14 +498,14 @@ server if you want to know how difficult an issue likely is.
The severity label categorizes what type of issue is described by an issue, or
what is implemented by a pull request.

- **S-bug**: This is a bug in the console. If this label is added to an issue,
* **S-bug**: This is a bug in the console. If this label is added to an issue,
then that issue describes a bug. If this label is added to a pull request,
then this pull request *fixes* a bug.
- **S-feature**: This is adding a new feature.
- **S-performance**: Related to improving performance, either in the
then this pull request _fixes_ a bug.
* **S-feature**: This is adding a new feature.
* **S-performance**: Related to improving performance, either in the
instrumented application or in the `console` CLI. This may be added to
performance regressions that don't result in a crash or incorrect data, as
well as to pull requests that implement optimizations.
- **S-refactor**: This is a refactor. This label describes proposed or
* **S-refactor**: This is a refactor. This label describes proposed or
implemented changes that are related to improve code quality or set up for
future changes, but shouldn't effect behavior, fix bugs, or add new APIs.
32 changes: 19 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,10 @@ toolkit consists of multiple components:
[`tracing`].

* tools for **displaying and exploring diagnostic data**, implemented as gRPC
clients using the console wire protocol. the [`tokio-console`] crate implements an
**an interactive command-line tool** that consumes this data, but **other
implementations**, such as graphical or web-based tools, are also possible.
clients using the console wire protocol. the [`tokio-console`] crate
implements an **an interactive command-line tool** that consumes this data,
but **other implementations**, such as graphical or web-based tools, are
also possible.

[gRPC]: https://grpc.io/
[protocol buffers]: https://developers.google.com/protocol-buffers
Expand All @@ -58,7 +59,7 @@ viewing details for a single task:

![task details view](https://user-images.githubusercontent.com/2796466/129774524-288c967b-6066-4f98-973d-099b3e6a2c55.png)

## on the shoulders of giants...
## on the shoulders of giants

the console is **part of a much larger effort** to improve debugging tooling for
async Rust. **a [2019 Google Summer of Code project][gsoc] by Matthias Prechtl**
Expand Down Expand Up @@ -86,7 +87,9 @@ others.
[Instruments]: https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/MeasuringPerformance.html
[**@matprec**]: https://github.com/matprec
[**@pnkfelix**]: https://github.com/pnkfelix

## using it

### instrumenting your program

to **instrument an application using Tokio**, add a dependency on the
Expand All @@ -101,10 +104,13 @@ notes:

* in order to collect task data from Tokio, **the `tokio_unstable` cfg must be
enabled**. for example, you could build your project with

```shell
$ RUSTFLAGS="--cfg tokio_unstable" cargo build
RUSTFLAGS="--cfg tokio_unstable" cargo build
```

or add the following to your `.cargo/config.toml` file:

```toml
[build]
rustflags = ["--cfg", "tokio_unstable"]
Expand All @@ -116,29 +122,29 @@ notes:
* the `tokio` and `runtime` [`tracing` targets] must be enabled at the [`TRACE`
level].

+ if you're using the [`console_subscriber::init()`][init] or
* if you're using the [`console_subscriber::init()`][init] or
[`console_subscriber::Builder`][builder] APIs, these targets are enabled
automatically.

+ if you are manually configuring the `tracing` subscriber using the
* if you are manually configuring the `tracing` subscriber using the
[`EnvFilter`] or [`Targets`] filters from [`tracing-subscriber`], add
`"tokio=trace,runtime=trace"` to your filter configuration.

+ also, ensure you have not enabled any of the [compile time filter
* also, ensure you have not enabled any of the [compile time filter
features][compile_time_filters] in your `Cargo.toml`.

### running the console

to **run the console command-line tool**, install `tokio-console` from [crates.io](https://crates.io/crates/tokio-console)

```shell
$ cargo install --locked tokio-console
cargo install --locked tokio-console
```

and run locally

```shell
$ tokio-console
tokio-console
```

> **alternative method:** run the tool from a local checkout of this repository
Expand All @@ -154,14 +160,14 @@ as an argument to the console (either as an `<IP>:<PORT>` or
`<DNS_NAME>:<PORT>`). for example:
```shell
$ cargo run -- http://my.great.console.app.local:5555
cargo run -- http://my.great.console.app.local:5555
```
the console command-line tool supports a number of additional flags to configure
its behavior. the `-h` or `--help` flag will print a list of supported
command-line flags and arguments:
```
```text
USAGE:
tokio-console [FLAGS] [OPTIONS] [TARGET_ADDR]
Expand Down Expand Up @@ -240,7 +246,7 @@ OPTIONS:
* `years`, `year`, `y` -- defined as 365.25 days [default: 6s]
```
## for development:
## for development
the `console-subscriber/examples` directory contains **some potentially useful
tools**:
Expand Down
2 changes: 2 additions & 0 deletions SECURITY.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Security

## Report a security issue

The Tokio project team welcomes security reports and is committed to providing prompt attention to security issues. Security issues should be reported privately via [security@tokio.rs](mailto:security@tokio.rs). Security issues should not be reported via the public Github Issue tracker.
Expand Down

0 comments on commit 8e3c6c5

Please sign in to comment.