doc: update release instructions (#845)

Importantly:

- Document how to test actors.
- Document the crate structure.

CONTRIBUTING.md

@@ -24,29 +24,58 @@ To make a change to the FVM.
 
 To prepare a release.
 
-1. Pick a next version (for each crate you're releasing). Look through the changelogs and carefully
+1. Make sure the crate's `CHANGELOG.md` is up-to-date (look through `git log -- path/to/crate`).
+2. Make sure the changes are well tested. See [builtin actors testing][builtin actors testing].
+3. Pick a next version (for each crate you're releasing). Look through the changelogs and carefully
    decide if it's a breaking release or not. Then read [rust's semver
    documentation](https://doc.rust-lang.org/cargo/reference/semver.html).
-2. Install `cargo-edit` (`cargo install cargo-edit`).
-3. Create a new branch.
-4. Use `cargo set-version` to set the version for each crate you're releasing. This will both update
+4. Install `cargo-edit` (`cargo install cargo-edit`).
+5. Create a new branch.
+6. Use `cargo set-version` to set the version for each crate you're releasing. This will both update
    the crate version, and make all other crates in the workspace depend on the latest version.
-5. Make sure the changelogs are all up-to-date, set the release date & version, and add a new
+7. Make sure the changelogs are all up-to-date, set the release date & version, and add a new
    "Unreleased" section.
-6. Commit your changes, and make a PR.
+8. Commit your changes, and make a PR.
 
 Once the release is prepared, it'll go through a review:
 
 1. Make sure that we're _ready_ to release. E.g., make sure downstream can consume the release.
 2. Make sure that we're correctly following semver.
 3. Make sure that we're not missing anything in the changelogs.
 
-Finally, an FVM "owner" will:
+Finally, an [FVM "owner"](https://github.com/orgs/filecoin-project/teams/fvm-crate-owners/members) will:
 
 1. Merge the release PR to master.
 2. For each released crate, create a git: `crate_name@crate_version`.
 3. Run `cargo publish` for each released crate (in dependency order).
 
+### Crate Dependency Graph
+
+The crates in this workspace have the following structure:
+
+![Workspace Graph](./doc/workspace.png)
+
+### Builtin-Actors Testing
+
+If you're releasing any non-trivial changes to crates used by the builtin actors, please test them. This includes:
+
+- Any crates in `ipld/` except `car`.
+- `shared/` (`fvm_shared`).
+- `sdk/` (`fvm_sdk`).
+
+To test:
+
+1. Checkout this repo as `ref-fvm/` and and the builtin-actors repo as `builtin-actors/` in the same directory.
+2. Uncomment the "patch" section in `builtin-actors/Cargo.toml` that starts with:
+    ```toml
+    [patch.crates-io]
+    fvm_shared = { path = "../ref-fvm/shared" }
+    ...
+    ```
+3. Run `cargo test --all` (or, at a minimum, `cargo check --all --tests --lib`.
+
+If that works, proceed with releasing these crates.
+
 [chat]: https://docs.filecoin.io/about-filecoin/chat-and-discussion-forums/#chat
 [discuss]: https://github.com/filecoin-project/fvm-specs/discussions
 [issue]: https://github.com/filecoin-project/ref-fvm/issues

doc/workspace.dot

@@ -0,0 +1,30 @@
+digraph {
+    fvm;
+    fvm_ipld_amt;
+    fvm_ipld_Blockstore;
+    fvm_ipld_encoding;
+    fvm_ipld_hamt;
+    fvm_shared;
+    fvm_sdk;
+    fvm_ipld_car;
+    fvm_ipld_Bitfield;
+
+    fvm -> fvm_ipld_amt;
+    fvm -> fvm_ipld_Blockstore;
+    fvm -> fvm_ipld_encoding;
+    fvm -> fvm_ipld_hamt;
+    fvm -> fvm_shared;
+    fvm_ipld_amt -> fvm_ipld_Blockstore;
+    fvm_ipld_amt -> fvm_ipld_encoding;
+    fvm_ipld_encoding -> fvm_ipld_Blockstore;
+    fvm_ipld_hamt -> fvm_ipld_Blockstore;
+    fvm_ipld_hamt -> fvm_ipld_encoding;
+    fvm_shared -> fvm_ipld_Blockstore;
+    fvm_shared -> fvm_ipld_encoding;
+    fvm_sdk -> fvm_ipld_encoding;
+    fvm_sdk -> fvm_shared;
+    fvm_ipld_car -> fvm_ipld_Blockstore;
+    fvm_ipld_car -> fvm_ipld_encoding;
+    fvm_ipld_Bitfield -> fvm_ipld_encoding;
+}
+