vendor/zerocopy/INTERNAL.md

   1 <!-- Copyright 2022 The Fuchsia Authors
   2
   3 Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
   4 <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
   5 license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
   6 This file may not be copied, modified, or distributed except according to
   7 those terms. -->
   8
   9 # Internal details
  10
  11 This file documents various internal details of zerocopy and its infrastructure
  12 that consumers don't need to be concerned about. It focuses on details that
  13 affect multiple files, and allows each affected code location to reference this
  14 document rather than requiring us to repeat the same explanation in multiple
  15 locations.
  16
  17 ## CI and toolchain versions
  18
  19 In CI (`.github/workflows/ci.yml`), we pin to specific versions or dates of the
  20 stable and nightly toolchains. The reason is twofold: First, our UI tests (see
  21 `tests/trybuild.rs` and `zerocopy-derive/tests/trybuild.rs`) depend on the
  22 format of rustc's error messages, and that format can change between toolchain
  23 versions (we also maintain multiple copies of our UI tests - one for each
  24 toolchain version pinned in CI - for this reason). Second, not all nightlies
  25 have a working Miri, so we need to pin to one that does (see
  26 https://rust-lang.github.io/rustup-components-history/).
  27
  28 Updating the versions pinned in CI may cause the UI tests to break. In order to
  29 fix UI tests after a version update, run:
  30
  31 ```
  32 $ TRYBUILD=overwrite ./cargo.sh +all test
  33 ```
  34
  35 ## Crate versions
  36
  37 We ensure that the crate versions of zerocopy and zerocopy-derive are always the
  38 same in-tree, and that zerocopy depends upon zerocopy-derive using an exact
  39 version match to the current version in-tree. This has the result that, even
  40 when published on crates.io, both crates effectively constitute a single atomic
  41 version. So long as the code in zerocopy is compatible with the code in
  42 zerocopy-derive in the same Git commit, then publishing them both is fine. This
  43 frees us from the normal task of reasoning about compatibility with a range of
  44 semver-compatible versions of different crates.