Skip to content

Commit

Permalink
docs: consistent MSRV docs & policy explanation (#941)
Browse files Browse the repository at this point in the history 
## Motivation

PR #934 fixed a bug in the CI configuration where MSRV checks were not
being run correctly. After this was fixed, it was necessary to bump the
MSRV to 1.40.0, as the tests were no longer actually passing on 1.39,
because some dependencies no longer support it.

While updating the documentation to indicate that the new MSRV is 1.40,
I noticed that the note on the MSRV was located inconsistently in the
READMEs and `lib.rs` documentation of various crates, and missing
entirely in some cases. Additionally, there have been some questions on
what our MSRV _policies_ are, and whether MSRV bumps are considered
breaking changes (see e.g. #936). 

## Solution

I've updated all the MSRV notes in the documentation and READMEs to
indicate that the MSRV is 1.40. I've also ensured that the MSRV note is
in the same place for every crate (at the end of the "Overview" section
in the docs), and that it's formatted consistently.

Furthermore, I added a new section to the READMEs and `lib.rs` docs
explaining the current MSRV policy in some detail. Hopefully, this
should answer questions like #936 in the future. The MSRV note in the
overview section includes a link to the section with further details.

Finally, while doing this, I noticed a couple of crates
(`tracing-journald` and `tracing-serde`) were missing top-level `lib.rs`
docs. Rather than just adding an MSRV note and nothing else, I went
ahead and fixed this using documentation from those crate's READMEs.

Signed-off-by: Eliza Weisman <[email protected]>
  • Loading branch information
@hawkw
hawkw authored Aug 18, 2020
1 parent 1e086e8 commit 3f8280a
Show file tree
Hide file tree
Showing 26 changed files with 611 additions and 29 deletions.
13 changes: 13 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,19 @@ attachment that `Future::instrument` does.
[`Future::instrument`]: https://docs.rs/tracing-futures/latest/tracing_futures/trait.Instrument.html#method.instrument
[instrument]: https://docs.rs/tracing/0.1.14/tracing/attr.instrument.html

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## Getting Help

Expand Down
18 changes: 18 additions & 0 deletions tracing-appender/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ allows events and spans to be recorded in a non-blocking manner through a
dedicated logging thread. It also provides a [`RollingFileAppender`][file_appender]
that can be used with _or_ without the non-blocking writer.

*Compiler support: [requires `rustc` 1.40+][msrv]*

[msrv]: #supported-rust-versions

## Usage

Add the following to your `Cargo.toml`:
Expand Down Expand Up @@ -139,6 +143,20 @@ fn main() {
[file_appender]: https://docs.rs/tracing-appender/latest/tracing_appender/rolling/struct.RollingFileAppender.html
[fmt_subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## License

This project is licensed under the [MIT license](../LICENSE).
Expand Down
18 changes: 18 additions & 0 deletions tracing-appender/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
//! a dedicated logging thread. It also provides a [`RollingFileAppender`][file_appender] that can
//! be used with _or_ without the non-blocking writer.
//!
//! *Compiler support: [requires `rustc` 1.40+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//! [file_appender]: ./rolling/struct.RollingFileAppender.html
//! [tracing]: https://docs.rs/tracing/
//!
Expand Down Expand Up @@ -104,6 +107,21 @@
//! .init();
//! # }
//! ```
//!
//! ## Supported Rust Versions
//!
//! Tracing is built against the latest stable release. The minimum supported
//! version is 1.40. The current Tracing version is not guaranteed to build on
//! Rust versions earlier than the minimum supported version.
//!
//! Tracing follows the same compiler support policies as the rest of the Tokio
//! project. The current stable Rust compiler and the three most recent minor
//! versions before it will always be supported. For example, if the current
//! stable compiler version is 1.45, the minimum supported version will not be
//! increased past 1.42, three minor versions prior. Increasing the minimum
//! supported compiler version is not considered a semver breaking change as
//! long as doing so complies with this policy.
//!
#![doc(html_root_url = "https://docs.rs/tracing-appender/0.1.1")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg",
Expand Down
20 changes: 18 additions & 2 deletions tracing-attributes/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ structured, event-based diagnostic information. This crate provides the

Note that this macro is also re-exported by the main `tracing` crate.

*Compiler support: [requires `rustc` 1.40+][msrv]*

[msrv]: #supported-rust-versions

## Usage

First, add this to your `Cargo.toml`:
Expand All @@ -46,7 +50,6 @@ First, add this to your `Cargo.toml`:
tracing-attributes = "0.1.10"
```

*Compiler support: requires rustc 1.39+*

This crate provides the `#[instrument]` attribute for instrumenting a function
with a `tracing` [span]. For example:
Expand All @@ -60,10 +63,23 @@ pub fn my_function(my_arg: usize) {
}
```


[`tracing`]: https://crates.io/crates/tracing
[span]: https://docs.rs/tracing/latest/tracing/span/index.html

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## License

This project is licensed under the [MIT license](LICENSE).
Expand Down
21 changes: 19 additions & 2 deletions tracing-attributes/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
//!
//! Note that this macro is also re-exported by the main `tracing` crate.
//!
//! *Compiler support: [requires `rustc` 1.40+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//!
//! ## Usage
//!
//! First, add this to your `Cargo.toml`:
Expand All @@ -15,8 +19,6 @@
//! tracing-attributes = "0.1.10"
//! ```
//!
//! *Compiler support: requires rustc 1.39+*
//!
//! The [`#[instrument]`][instrument] attribute can now be added to a function
//! to automatically create and enter `tracing` [span] when that function is
//! called. For example:
Expand All @@ -35,6 +37,21 @@
//! [`tracing`]: https://crates.io/crates/tracing
//! [span]: https://docs.rs/tracing/latest/tracing/span/index.html
//! [instrument]: attr.instrument.html
//!
//! ## Supported Rust Versions
//!
//! Tracing is built against the latest stable release. The minimum supported
//! version is 1.40. The current Tracing version is not guaranteed to build on
//! Rust versions earlier than the minimum supported version.
//!
//! Tracing follows the same compiler support policies as the rest of the Tokio
//! project. The current stable Rust compiler and the three most recent minor
//! versions before it will always be supported. For example, if the current
//! stable compiler version is 1.45, the minimum supported version will not be
//! increased past 1.42, three minor versions prior. Increasing the minimum
//! supported compiler version is not considered a semver breaking change as
//! long as doing so complies with this policy.
//!
#![doc(html_root_url = "https://docs.rs/tracing-attributes/0.1.10")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg",
Expand Down
24 changes: 20 additions & 4 deletions tracing-core/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,12 @@ The crate provides:
In addition, it defines the global callsite registry and per-thread current
dispatcher which other components of the tracing system rely on.

## Usage
*Compiler support: [requires `rustc` 1.40+][msrv]*

[msrv]: #supported-rust-versions

## Usage

Application authors will typically not use this crate directly. Instead, they
will use the [`tracing`] crate, which provides a much more fully-featured
API. However, this crate's API will change very infrequently, so it may be used
Expand All @@ -71,15 +75,13 @@ The following crate feature flags are available:

* `std`: Depend on the Rust standard library (enabled by default).

`no_std` users may disable this feature with `default-features = false`:
`no_std` users may disable this feature with `default-features = false`:

```toml
[dependencies]
tracing-core = { version = "0.1.14", default-features = false }
```

*Compiler support: requires rustc 1.39+*

**Note**:`tracing-core`'s `no_std` support requires `liballoc`.

[`tracing`]: ../tracing
Expand All @@ -94,6 +96,20 @@ The following crate feature flags are available:
[`ValueSet`]: https://docs.rs/tracing-core/0.1.14/tracing_core/field/struct.ValueSet.html
[`Dispatch`]: https://docs.rs/tracing-core/0.1.14/tracing_core/dispatcher/struct.Dispatch.html

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## License

This project is licensed under the [MIT license](LICENSE).
Expand Down
21 changes: 19 additions & 2 deletions tracing-core/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
//! In addition, it defines the global callsite registry and per-thread current
//! dispatcher which other components of the tracing system rely on.
//!
//! *Compiler support: [requires `rustc` 1.40+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//!
//! ## Usage
//!
//! Application authors will typically not use this crate directly. Instead,
Expand Down Expand Up @@ -52,10 +56,23 @@
//! tracing-core = { version = "0.1.14", default-features = false }
//! ```
//!
//! *Compiler support: requires rustc 1.39+*
//!
//! **Note**:`tracing-core`'s `no_std` support requires `liballoc`.
//!
//! ## Supported Rust Versions
//!
//! Tracing is built against the latest stable release. The minimum supported
//! version is 1.40. The current Tracing version is not guaranteed to build on
//! Rust versions earlier than the minimum supported version.
//!
//! Tracing follows the same compiler support policies as the rest of the Tokio
//! project. The current stable Rust compiler and the three most recent minor
//! versions before it will always be supported. For example, if the current
//! stable compiler version is 1.45, the minimum supported version will not be
//! increased past 1.42, three minor versions prior. Increasing the minimum
//! supported compiler version is not considered a semver breaking change as
//! long as doing so complies with this policy.
//!
//!
//! [`span::Id`]: span/struct.Id.html
//! [`Event`]: event/struct.Event.html
//! [`Subscriber`]: subscriber/trait.Subscriber.html
Expand Down
18 changes: 17 additions & 1 deletion tracing-error/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ The crate provides the following:

**Note**: This crate is currently experimental.

*Compiler support: requires `rustc` 1.39+*
*Compiler support: [requires `rustc` 1.40+][msrv]*

[msrv]: #supported-rust-versions

## Usage

Expand Down Expand Up @@ -181,6 +183,20 @@ fn main() {
- [`ExtractSpanTrace`] extension trait, for extracting `SpanTrace`s from
behind `dyn Error` trait objects.

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## Related Crates

In addition to this repository, here are also several third-party crates which
Expand Down
19 changes: 18 additions & 1 deletion tracing-error/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@
//!
//! **Note**: This crate is currently experimental.
//!
//! *Compiler support: requires `rustc` 1.39+*
//! *Compiler support: [requires `rustc` 1.40+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//!
//! ## Feature Flags
//!
Expand Down Expand Up @@ -168,6 +170,21 @@
//! [subscriber layer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html
//! [`tracing`]: https://docs.rs/tracing
//! [`std::error::Error`]: https://doc.rust-lang.org/stable/std/error/trait.Error.html
//!
//! ## Supported Rust Versions
//!
//! Tracing is built against the latest stable release. The minimum supported
//! version is 1.40. The current Tracing version is not guaranteed to build on
//! Rust versions earlier than the minimum supported version.
//!
//! Tracing follows the same compiler support policies as the rest of the Tokio
//! project. The current stable Rust compiler and the three most recent minor
//! versions before it will always be supported. For example, if the current
//! stable compiler version is 1.45, the minimum supported version will not be
//! increased past 1.42, three minor versions prior. Increasing the minimum
//! supported compiler version is not considered a semver breaking change as
//! long as doing so complies with this policy.
//!
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(html_root_url = "https://docs.rs/tracing-error/0.1.2")]
#![doc(
Expand Down
17 changes: 17 additions & 0 deletions tracing-flame/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ flamegraph/flamechart. Flamegraphs/flamecharts are useful for identifying perfor
bottlenecks in an application. For more details, see Brendan Gregg's [post]
on flamegraphs.

*Compiler support: [requires `rustc` 1.40+][msrv]*

[msrv]: #supported-rust-versions
[post]: http://www.brendangregg.com/flamegraphs.html

## Usage
Expand Down Expand Up @@ -101,6 +104,20 @@ span is entered relative to others and get an accurate visual trace of
the execution of your program. This representation is best created with a
_flamechart_, which _does not_ sort or collapse identical stack frames.

## Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported
version is 1.40. The current Tracing version is not guaranteed to build on Rust
versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio
project. The current stable Rust compiler and the three most recent minor
versions before it will always be supported. For example, if the current stable
compiler version is 1.45, the minimum supported version will not be increased
past 1.42, three minor versions prior. Increasing the minimum supported compiler
version is not considered a semver breaking change as long as doing so complies
with this policy.

## License

This project is licensed under the [MIT license](LICENSE).
Expand Down
18 changes: 18 additions & 0 deletions tracing-flame/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@
//! issues bottlenecks in an application. For more details, see Brendan Gregg's [post]
//! on flamegraphs.
//!
//! *Compiler support: [requires `rustc` 1.40+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//! [post]: http://www.brendangregg.com/flamegraphs.html
//!
//! ## Usage
Expand Down Expand Up @@ -91,6 +94,21 @@
//! [`FlameLayer`]: struct.FlameLayer.html
//! [`FlushGuard`]: struct.FlushGuard.html
//! [`inferno-flamegraph`]: https://docs.rs/inferno/0.9.5/inferno/index.html#producing-a-flame-graph
//!
//! ## Supported Rust Versions
//!
//! Tracing is built against the latest stable release. The minimum supported
//! version is 1.40. The current Tracing version is not guaranteed to build on
//! Rust versions earlier than the minimum supported version.
//!
//! Tracing follows the same compiler support policies as the rest of the Tokio
//! project. The current stable Rust compiler and the three most recent minor
//! versions before it will always be supported. For example, if the current
//! stable compiler version is 1.45, the minimum supported version will not be
//! increased past 1.42, three minor versions prior. Increasing the minimum
//! supported compiler version is not considered a semver breaking change as
//! long as doing so complies with this policy.
//!
#![doc(
html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg",
issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
Expand Down
Loading

0 comments on commit 3f8280a

Please sign in to comment.