I'm going to use this comment to draft the upgrading guide.

Zerocopy 0.7 -> 0.8 Upgrading Guide

Thank you for using zerocopy! Our new 0.8 release includes a number of changes which are backwards-incompatible with 0.7. This guide describes these changes and gives advice for how to make the upgrade process as painless as possible.

For large codebases, it may help to automate some of these upgrading steps using a tool such as ast-grep.

Implied derives

The FromBytes trait is a sub-trait of FromZeros. On 0.7, in order to derive FromBytes, you also had to derive FromZeros explicitly:

#[derive(FromZeros, FromBytes)]
struct Foo { ... }

On 0.8, deriving a trait automatically derives its super-traits. This code will now fail to compile since the FromBytes derive will emit an impl of FromZeros, which will conflict with the impl derived by the explicit FromZeros derive. Instead, simply write:

#[derive(FromBytes)]
struct Foo { ... }

New names

The AsBytes trait has been renamed to IntoBytes. The FromZeroes trait has been renamed to FromZeros.

A number of Ref, FromBytes, and IntoBytes methods have been renamed or deprecated in favor of a more general method. The old methods are preserved and marked as #[doc(hidden)] #[deprecated], including a deprecation message that indicates which API should be preferred in 0.8. We recommend using these compilation warnings as a guide for how to upgrade individual call sites. As they are #[doc(hidden)], we do not consider these methods subject to semver guarantees, and they may be removed or re-used in any future 0.8 version.

New traits

FromBytes and IntoBytes

Some properties that were previously required by FromBytes or IntoBytes (previously AsBytes) have now been split into separate traits. APIs that still require those properties now add bounds on these new traits.

The new traits in question are KnownLayout, which encodes certain layout information about a type, and Immutable, which indicates that a type does not contain any UnsafeCells.

We recommend that you simply derive KnownLayout and Immutable on any type with existing zerocopy trait derives. Alternatively, for a more fine-grained approach, use compilation errors as a guide to which types should derive these traits.

ByteSlice

The ByteSlice trait now supports byte slices which cannot be cheaply split in two. The new SplitByteSlice trait extends ByteSlice with this behavior. In 0.8, SplitByteSlice is analogous to what ByteSlice was in 0.7. The same holds for ByteSliceMut and SplitByteSliceMut.

If you don't care about maximum flexibility, we recommend simply replacing all instances of ByteSlice[Mut] with SplitByteSlice[Mut]. Alternatively, if you wish to support ByteSlice[Mut] types which cannot be split, use compilation errors as a guide to where you need to add SplitByteSlice[Mut] bounds.

New return values

Many methods that previously returned Option now return Result, and include a finer-grained error type. If you wish to preserve the 0.7 behavior and minimize the code change needed to upgrade, simply add .ok() to these call sites in order to convert Results back into Options. However, we recommend that most code should try to migrate to the new error types eventually, as they will help you ensure that you're only handling errors that you expect. For example, having to handle an AlignmentError where you don't expect it is an indication that you could use a different API that guarantees freedom from alignment errors (e.g. one of the Ref methods with unaligned in the method name).

Miscellaneous

The byteorder feature has been removed; in 0.8, the byteorder module is always present, and is not optional.

Upgrading guide is published in our release announcement. We won't write an upgrading tool.