diff --git a/CHANGELOG.md b/CHANGELOG.md index 840349d..913649e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - ReleaseDate +## [0.6.8] - 2022-04-04 +### Added +- Add `#[must_use]` to `Report` +- Add `must-install` feature to help reduce binary sizes when using a custom `EyreHandler` + ## [0.6.7] - 2022-02-24 ### Fixed - added missing track_caller annotation to new format arg capture constructor @@ -38,7 +43,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 -[Unreleased]: https://github.com/yaahc/eyre/compare/v0.6.7...HEAD +[Unreleased]: https://github.com/yaahc/eyre/compare/v0.6.8...HEAD +[0.6.8]: https://github.com/yaahc/eyre/compare/v0.6.7...v0.6.8 [0.6.7]: https://github.com/yaahc/eyre/compare/v0.6.6...v0.6.7 [0.6.6]: https://github.com/yaahc/eyre/compare/v0.6.5...v0.6.6 [0.6.5]: https://github.com/yaahc/eyre/compare/v0.6.4...v0.6.5 diff --git a/Cargo.toml b/Cargo.toml index e38ad9e..11556f2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "eyre" -version = "0.6.7" +version = "0.6.8" authors = ["David Tolnay ", "Jane Lusby "] edition = "2018" license = "MIT OR Apache-2.0" diff --git a/README.md b/README.md index 52da2bb..08c0815 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,29 @@ handlers for eyre and short summaries of what features they provide. - [`jane-eyre`]: A report handler crate that exists purely for the pun of it. Currently just re-exports `color-eyre`. +## Usage Recommendations and Stability Considerations + +**We recommend users do not re-export types from this library as part their own +public API for libraries with external users.** The main reason for this is +that it will make your library API break if we ever bump the major version +number on eyre and your users upgrade the eyre version they use in their +application code before you upgrade your own eyre dep version[^1]. + +However, even beyond this API stability hazard, there are other good reasons to +avoid using `eyre::Report` as your public error type. + +- You export an undocumented error interface that is otherwise still accessible + via downcast, making it hard for users to react to specific errors while not + preventing them from depending on details you didn't mean to make part of + your public API. + - This in turn makes the error types of all libraries you use a part of your + public API as well, and makes changing any of those libraries into an + undetectable runtime breakage. +- If many of your errors are constructed from strings you encourage your users + to use string comparision for reacting to specific errors which is brittle + and turns updating error messages into a potentially undetectable runtime + breakage. + ## Details - Use `Result`, or equivalently `eyre::Result`, as the @@ -233,6 +256,7 @@ implements `context` for options which you can import to make existing [`color-spantrace`]: https://github.com/yaahc/color-spantrace [`color-backtrace`]: https://github.com/athre0z/color-backtrace +[^1]: example and explanation of breakage https://github.com/yaahc/eyre/issues/30#issuecomment-647650361 #### License diff --git a/src/lib.rs b/src/lib.rs index f19aaa0..e7251c2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,6 +27,29 @@ //! - [`jane-eyre`]: A report handler crate that exists purely for the pun. //! Currently just re-exports `color-eyre`. //! +//! ## Usage Recommendations and Stability Considerations +//! +//! **We recommend users do not re-export types from this library as part their +//! own public API for libraries with external users.** The main reason for this +//! is that it will make your library API break if we ever bump the major version +//! number on eyre and your users upgrade the eyre version they use in their +//! application code before you upgrade your own eyre dep version[^1]. +//! +//! However, even beyond this API stability hazard, there are other good reasons +//! to avoid using `eyre::Report` as your public error type. +//! +//! - You export an undocumented error interface that is otherwise still +//! accessible via downcast, making it hard for users to react to specific +//! errors while not preventing them from depending on details you didn't mean +//! to make part of your public API. +//! - This in turn makes the error types of all libraries you use a part of +//! your public API as well, and makes changing any of those libraries into an +//! undetectable runtime breakage. +//! - If many of your errors are constructed from strings you encourage your +//! users to use string comparision for reacting to specific errors which is +//! brittle and turns updating error messages into a potentially undetectable +//! runtime breakage. +//! //! ## Details //! //! - Use `Result`, or equivalently `eyre::Result`, as the @@ -290,6 +313,8 @@ //! implements `context` for options which you can import to make existing //! `.context` calls compile. //! +//! [^1]: example and explanation of breakage https://github.com/yaahc/eyre/issues/30#issuecomment-647650361 +//! //! [Report]: https://docs.rs/eyre/*/eyre/struct.Report.html //! [`eyre::EyreHandler`]: https://docs.rs/eyre/*/eyre/trait.EyreHandler.html //! [`eyre::WrapErr`]: https://docs.rs/eyre/*/eyre/trait.WrapErr.html @@ -302,7 +327,7 @@ //! [`simple-eyre`]: https://github.com/yaahc/simple-eyre //! [`color-spantrace`]: https://github.com/yaahc/color-spantrace //! [`color-backtrace`]: https://github.com/athre0z/color-backtrace -#![doc(html_root_url = "https://docs.rs/eyre/0.6.7")] +#![doc(html_root_url = "https://docs.rs/eyre/0.6.8")] #![warn( missing_debug_implementations, missing_docs,