Write 0.8 upgrading guide (and maybe write a cargo fix-like tool)

[joshlf]

Progress

• Write upgrading guide
• (optional) Write upgrading tool
  • Commit example zerocopy project along with CI test that tests the upgrade tool (this will help us keep the tool up-to-date as we make further API tweaks)

Details

As described in #1288 (comment), and in my own personal experience upgrading the version of zerocopy vendored in Fuchsia, upgrading from 0.7 to 0.8 creates a large amount of churn. This falls into a few primary buckets:

• Many APIs now require Immutable and/or KnownLayout
• #[derive(FromZeroes, FromBytes)] now breaks, and needs to be replaced with just #[derive(FromBytes)]
• FromZeroes and AsBytes have been renamed to FromZeros and IntoBytes, respectively
• Many methods have been deprecated and need to be replaced by calls to different methods
• The return type of fallible methods has gone from Option to Result
• Some APIs that previously required B: ByteSlice now require B: SplitByteSlice

Upgrading guide

We should at a minimum write a detailed upgrading guide that explains what changes will need to be made, and what compiler errors to expect.

We may also want to include a note about the byteorder feature being removed.

Upgrade tool

We may also want to write a cargo fix-like tool that performs some of the upgrade automatically, as much of this can be done mechanically. In particular, the following set of transformations would result in code which is nearly semantically identical under 0.8:

• Rename FromZeroes and AsBytes to FromZeros and IntoBytes
• Everywhere FromZeros, FromBytes, or AsBytes is used (especially in derives and in trait bounds), add Immutable and KnownLayout as well
• Everywhere both FromZeros and FromBytes are derived, remove FromZeros
• Replace calls to deprecated methods with calls to their replacements
• Add .ok() to most FromBytes methods and Ref constructors
• Replace ByteSlice with SplitByteSlice in trait bounds

Some of these could be done with a relatively low false positive rate just using standard unix shell tools. Some of them would be better served by a more powerful tool that can parse Rust code and resolve item paths (e.g., detecting whether a use of Ref::new refers to zerocopy::Ref or some other Ref).

A few suggestions from this thread:

• ast-grep
  • Here's an example of rewriting a #[derive]
• "If you do not mind changing the formatting, you may use the syn crate with the visitor feature to browse and edit the code, then prettyplease to get a readable output."
• Write a rustc-driver plugin
• rust-analyzer search and replace
• gritql
• VSCode refactoring action