Merge pull request #428 from shepmaster/changelog

Update the changelog and upgrading guide in preparation for 0.8

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

src/guide/upgrading.md

@@ -1,12 +1,96 @@
 # 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)
 - [Version 0.3 → 0.4](#version-03--04)
 - [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