docs: summarizing how network upgrades impact Lotus and its key dependencies

LOTUS_RELEASE_FLOW.md

@@ -38,7 +38,7 @@ This document aims to describe how the Lotus maintainers ship releases of Lotus.
 
 - Lotus software use semantic versioning (`MAJOR`.`MINOR`.`PATCH`).
 - **`MAJOR` releases** are reserved for significant architectural changes to Lotus. 
-- **`MINOR` releases** are shipped for network upgrades, API breaking changes, or non-backwards-compatible feature enhancements.
+- **`MINOR` releases** are shipped for [network upgrades](./documentation/misc/Building_a_network_skeleton.md#context), API breaking changes, or non-backwards-compatible feature enhancements.
 - **`PATCH` releases** contain backwards-compatible bug fixes or feature enhancements.
 - Releases are almost always branched from the `master` branch, even if they include a network upgrade. The main exception is if there is a critical security patch we need to rush out. In that case, we would patch an existing release to increase release speed and reduce barrier to adoption.
 - We aim to ship a new release of the Lotus Node software approximately every 4 weeks, except during network upgrade periods which may have longer release cycles.
@@ -71,7 +71,8 @@ Bumps to the Lotus software minor version number (e.g., 1.28.0, 1.29.0) are used
 - API breaking changes
 - Non-backwards-compatible feature enhancements
 
-Users MUST upgrade to minor releases that include a network upgrade before a certain time to keep in sync with the Filecoin network. We recommend everyone to subscribe to status.filecoin.io for updates when these are happening, as well checking the release notes of a minor version. 
+Users MUST upgrade to minor releases that include a network upgrade before a certain time to keep in sync with the Filecoin network. We recommend everyone subscribe to status.filecoin.io for updates when these are happening, as well as checking the release notes of a minor version. ([Learn more about how network upgrades relate to Lotus and its key dependencies.](./documentation/misc/Building_a_network_skeleton.md#context))
+
 Users can decide whether to upgrade to minor version releases that don't include a network upgrade. They are still encouraged to upgrade so they get the latest functionality and improvements and deploy a smaller delta of new code when there is a subsequent minor release they must adopt as part of a network upgrade later. 
 
 ### Patch Releases

documentation/misc/Building_a_network_skeleton.md

@@ -1,14 +1,60 @@
-# Network Upgrade Skeleton in Lotus
+# Network Upgrade Skeleton in Lotus <!-- omit in toc -->
 
-This guide will walk you through the process of creating a skeleton for a network upgrade in Lotus. The process involves making changes in multiple repositories in the following order:
+This guide will walk you through the process of creating a skeleton for a network upgrade in Lotus. 
 
+- [Context](#context)
+  - [Network Upgrade Dependency Versions](#network-upgrade-dependency-versions)
+  - [Network Upgrade Dependency Relationships](#network-upgrade-dependency-relationships)
 - [Setup](#setup)
 - [Ref-FVM Checklist](#ref-fvm-checklist)
 - [Filecoin-FFI Checklist](#filecoin-ffi-checklist)
 - [Go-State-Types Checklist](#go-state-types-checklist)
 - [Lotus Checklist](#lotus-checklist)
 
-Each repository has its own set of steps that need to be followed. This guide will provide detailed instructions for each repository.
+Each repository has its own set of steps that need to be followed. This guide provides detailed instructions for each repository in the proper order.
+
+## Context
+
+### Network Upgrade Dependency Versions
+There are these versions at play for a network upgrade:
+- Network Version: an incrementing integer prefixed with `nv` that corresponds with the hard fork that Filecoin implementations coordinate around (e.g., nvX).
+- FVM Version: The ref-fvm crate version (e.g., FVM_MAJOR_VERSION.y.x).
+- Lotus Version: The Lotus go.mod version (e.g., 1.LOTUS_MINOR_VERSION.x).
+- Actor Version: The incrementing integer that is associated with a builtin-actors bundle.
+
+### Network Upgrade Dependency Relationships
+```mermaid
+graph TD
+    lotus[lotus]
+    ffi[filecoin-ffi]
+    gst[go-state-types]
+    ba[builtin-actors]
+    fvm[ref-fvm]
+    proofs[rust-filecoin-proofs-api]
+
+    lotus -->gst
+    lotus -->|via submodule| ffi
+    lotus -->|via pack script| ba
+
+    gst --> ba
+
+    ffi --> fvm
+    ffi --> proofs
+
+    ba --> fvm
+```
+
+The table below gives an overview of how Lotus and its critical dependencies relate to each other and are versioned relative to network versions.
+
+| Repo | <div style="width:250px">For every network upgrade (increase in Network Version)...</div> | Versioning Scheme | Versioning Docs | go.mod direct dependencies | cargo.toml direct dependencies | Other direct dependencies |
+| --- | --- | --- | --- | --- | --- | --- |
+| `lotus` | There is at least one `lotus` minor version. [^0] | <small>1.LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md#adopted-conventions) | `go-state-types` | n/a | * `filecoin-ffi` via git submodule<br/>* `builtin-actors` via pack script |
+| `filecoin-ffi` | There is at least one `filecoin-ffi` minor version (since `filecoin-ffi` tracks `lotus`). | <small>1.LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | | * `ref-fvm`<br/>* `rust-filecoin-proofs-api` | None |
+| `go-state-types` | There are zero or one `go-state-types` minor versions (since `go-state-types` minor versions track `builtin-actors` major versions) | <small>0.ACTORS_VERSION.x</small> | [link](https://github.com/filecoin-project/go-state-types?tab=readme-ov-file#versioning) | None | n/a | None |
+| `builtin-actors` | There are zero or one actors major versions (i.e., we can have a new network upgrade without an actors bump) | <small>ACTORS_VERSION.0.x</small> | [link](https://github.com/filecoin-project/builtin-actors?tab=readme-ov-file#versioning) | n/a |`ref-fvm` | None |
+| `ref-fvm` | There may be a major version bump. If there isn't, there is at least a minor version bump to enable support for the new network version. | <small>FVM_ MAJOR_VERSION.y.x</small> | [link](https://github.com/filecoin-project/ref-fvm?tab=readme-ov-file#versioning) | n/a | None | None |
+
+[^0]: Exceptional case of no Lotus minor version for when we have two-stage upgrades where one network version enables some new feature and the next version disables the deprecated feature.
 
 ## Setup
 

documentation/misc/Update_Dependencies_Lotus.md

@@ -2,10 +2,15 @@
 
 This guide will walk through how to update the most common dependencies in Lotus. These are the dependencies this guide currently covers:
 
-- [Ref-FVM](#updating-ref-fvm)
-- [Filecoin-FFI](#updating-filecoin-ffi)
-- [Go-State-Types](#updating-go-state-types)
-- [Builtin-Actors](#updating-builtin-actors)
+<!-- no toc -->
+- [Updating Ref-FVM](#updating-ref-fvm)
+- [Updating Filecoin-FFI](#updating-filecoin-ffi)
+- [Updating Go-State-Types](#updating-go-state-types)
+- [Updating Builtin-Actors](#updating-builtin-actors)
+
+## Context
+
+Updating these dependencies in Lotus is usually related to network upgrades.  See [building a network upgrade skeleton in Lotus context](./Building_a_network_skeleton.md#context) for information on the versions and relationships at play.
 
 ## Updating Ref-FVM
 
@@ -21,7 +26,7 @@ This guide will walk through how to update the most common dependencies in Lotus
 
 2. `git fetch` to ensure you have the latests changes for *filecoin-ffi*.
 
-3. `git checkout vX.XX.X` to checkout the version you want to update to.
+3. `git checkout vX.Y.Z` to checkout the version you want to update to.
 
 4. Then commit the update to your Lotus branch and open a PR for updating Filecoin-FFI.
 
@@ -43,10 +48,10 @@ This guide will walk through how to update the most common dependencies in Lotus
 
 1. In your `lotus` directory, `cd build/actors`.
 
-2. Run this script `./pack.sh vXX vXX.X.X-rcX` to pull in the builtin-actors bundle into your Lotus repo. 
+2. Run this script `./pack.sh vXX vX.Y.Z-rcX` to pull in the builtin-actors bundle into your Lotus repo. 
 
 - `vXX` is the network version you are bundling this builtin-actors for.
-- `vXX.X.X-rcX` is the builtin-actors release you are bundling.
+- `vX.Y.Z-rcX` is the builtin-actors release you are bundling.
 
 👉 Example of a [PR updating Builtin-Actors bundle](https://github.com/filecoin-project/lotus/pull/11682/)