Release 0.6.8 (#74)

* Update changelog for new release

* Add recommendations on API stability

* (cargo-release) version 0.6.8

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
 
 
 <!-- next-url -->
-[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

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "eyre"
-version = "0.6.7"
+version = "0.6.8"
 authors = ["David Tolnay <dtolnay@gmail.com>", "Jane Lusby <jlusby42@gmail.com>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"

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<T, eyre::Report>`, or equivalently `eyre::Result<T>`, 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
 

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<T, eyre::Report>`, or equivalently `eyre::Result<T>`, 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,