diff --git a/CHANGELOG.md b/CHANGELOG.md index 39b06ab..c2f475c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,56 @@ modifying code to account for new releases. [upgrading guide]: https://docs.rs/snafu/*/snafu/guide/upgrading/index.html +## [0.8.0] - 2023-12-xx + +### Added + +- `snafu(transparent)` allows creating compound error types that act + as if they were not present, delegating thier `Display` and `Error` + implementations to the source error. This is useful when aggregating + smaller errors that already completely explain the failure. + +- `ResultExt::boxed` and `ResultExt::boxed_local` are available to + convert an error value into an owned trait object. This is useful + when an error type is a generic controlled by the caller. + +### Changed + +- Rust 1.56 is now the *minimum* supported Rust version. This is a + **breaking change**. + +- Rust 1.65 is now the *default* supported Rust version. This is a + **breaking change**. + +- The item type of the `ChainCompat` iterator is now `&'a (dyn Error + + 'b)` to allow downcasting the error trait object to a concrete + type. This is a **breaking change**. + +- Error fields marked `location` are no longer automatically + implicitly created. This is a **breaking change**. + +- Adding `#[snafu]` attributes to the field of a tuple struct are now + errors. This is a **breaking change**. + +- The SNAFU copy of the `Error` trait now marks the `description` and + `cause` methods as deprecated, following the standard library's + example. This trait is only active when using SNAFU in a no_std + environment and no functional difference is intended. + +### Removed + +- The default `Display` implementation no longer includes the error + text of the source error. This is a **breaking change**. + +- The `backtraces` and `unstable-backtraces-impl-std` feature flags + have been removed. This is a **breaking change**. The `Backtrace` + type is now the standard library's `Backtrace` type when it is + available. + +### Fixed + +[0.8.0]: https://github.com/shepmaster/snafu/releases/tag/0.8.0 + ## [0.7.5] - 2023-07-09 ### Added diff --git a/src/guide/upgrading.md b/src/guide/upgrading.md index 7bc148c..39eaa37 100644 --- a/src/guide/upgrading.md +++ b/src/guide/upgrading.md @@ -1,5 +1,6 @@ # Upgrading from previous releases +- [Version 0.7 → 0.8](#version-07--08) - [Version 0.6 → 0.7](#version-06--07) - [Version 0.5 → 0.6](#version-05--06) - [Version 0.4 → 0.5](#version-04--05) @@ -7,6 +8,89 @@ - [Version 0.2 → 0.3](#version-02--03) - [Version 0.1 → 0.2](#version-01--02) +## Version 0.7 → 0.8 + +### Fields named `location` are no longer automatically implicitly generated + +Previously, fields named `location` would be implicitly +generated. However, this proved to be confusing and usually not what +users wanted. If you have `#[snafu(implicit(false))]` on a field named +`location`, that can be removed. If you are using this functionality, +you will need to add `#[snafu(implicit)]` on those fields. + +#### Before + +```rust,ignore +#[derive(Debug, Snafu)] +struct ErrorWithGeneratedLocation { + location: snafu::Location, +} + +#[derive(Debug, Snafu)] +struct ErrorWithNonGeneratedLocation { + #[snafu(implicit(false))] + location: usize, +} +``` + +#### After + +```rust,ignore +#[derive(Debug, Snafu)] +struct ErrorWithGeneratedLocation { + #[snafu(implicit)] + location: snafu::Location, +} + +#[derive(Debug, Snafu)] +struct ErrorWithNonGeneratedLocation { + location: usize, +} +``` + +### The default implementation of `Display` no longer includes the source + +To better follow the Error Handling Project Group's suggested +[guideline][], the generated implementation of `Display` no longer +includes the underlying source's `Display`. High quality error types +already define their own `Display` format strings via +`snafu(display(...))`, so this should not impact many users. + +To combine all `Display` messages in the entire error chain, you can +use higher-level tools like [`report`](macro@report) or [`Report`][] or +lower-level tools like [`CleanedErrorText`][]. + +If you wish to ignore the suggested guideline, you will need to add a +`Display` implementation that explicitly includes the source text. + +[guideline]: https://blog.rust-lang.org/inside-rust/2021/07/01/What-the-error-handling-project-group-is-working-towards.html#guidelines-for-implementing-displayfmt-and-errorsource + +#### Before + +```rust,ignore +#[derive(Debug, Snafu)] +struct ErrorWithDefaultDisplay { + source: std::io::Error, +} +``` + +#### After + +```rust,ignore +#[derive(Debug, Snafu)] +#[snafu(display("ErrorWithDefaultDisplay: {source}"))] +struct ErrorWithDefaultDisplay { + source: std::io::Error, +} +``` + +### Minimum supported version of Rust is now 1.56 + +If you are writing a library, you will need to increase your minimum +supported version of Rust to 1.56 or better. If you are writing an +application, you should be able to upgrade your installed compiler by +the same mechanism that you installed it. + ## Version 0.6 → 0.7 Upgrading should be a tedious but straightforward process. To assist