From 73c29f192d55ef51174539824df900ff409c7bc0 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Tue, 17 Sep 2024 13:59:04 -0700
Subject: [PATCH 01/11] docs: summarizing how network upgrades impact Lotus and
 its key dependencies

---
 LOTUS_RELEASE_FLOW.md                         |  5 +--
 .../misc/Building_a_network_skeleton.md       | 31 +++++++++++++++++--
 .../misc/Update_Dependencies_Lotus.md         | 19 +++++++-----
 3 files changed, 43 insertions(+), 12 deletions(-)

diff --git a/LOTUS_RELEASE_FLOW.md b/LOTUS_RELEASE_FLOW.md
index c0deca840f8..0d82d8faab3 100644
--- a/LOTUS_RELEASE_FLOW.md
+++ b/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 to subscribe to status.filecoin.io for updates when these are happening, as well 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
diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 440a4c87b86..48d278e8819 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -1,14 +1,37 @@
-# 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 will provide 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.
+- FVM Version: The ref-fvm vX.Y.Z crate version.
+- Lotus Version: The Lotus go.mod version.
+- Actor Version: The incrementing integer that is associated with a builtin-actors bundle.
+
+### Network Upgrade Dependency Relationships
+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 | For every network upgrade (increase in Network Version)... | Versioning Scheme | Versioning Docs | go.mod direct dependencies | cargo.toml direct dependencies | Other direct dependencies
+-- | -- | -- | -- | -- | -- | --
+`lotus` | There is at least one Lotus minor version. [^2] | 1.LOTUS_MINOR_VERSION.x | [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 `filecion-ffi` tracks `lotus`). | 1.LOTUS_MINOR_VERSION.x | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.ACTORS_VERSION.x | [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) | ACTORS_VERSION.0.x | [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. | FVM_ MAJOR_VERSION.y.x | [link](https://github.com/filecoin-project/ref-fvm?tab=readme-ov-file#versioning) | n/a | None | None
 
 ## Setup
 
@@ -178,6 +201,8 @@ And you're done! These are all the steps necessary to create a network upgrade s
 
 You can take a look at this [Lotus PR as a reference](https://github.com/filecoin-project/lotus/pull/11964), which added the skeleton for network version 23.
 
+[^7]: 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.
+
 [^1]: Here is system.go template for a simple migration:
 
     ```go
diff --git a/documentation/misc/Update_Dependencies_Lotus.md b/documentation/misc/Update_Dependencies_Lotus.md
index 71ab5de89b0..c937fc18d4b 100644
--- a/documentation/misc/Update_Dependencies_Lotus.md
+++ b/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/)
 

From 755fd45154ed66a79ef421f08495ad295974f28a Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Tue, 17 Sep 2024 14:13:21 -0700
Subject: [PATCH 02/11] Formatting updates

---
 .../misc/Building_a_network_skeleton.md       | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 48d278e8819..00373734d0c 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -11,27 +11,29 @@ This guide will walk you through the process of creating a skeleton for a networ
 - [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 in the proper order.
+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.
-- FVM Version: The ref-fvm vX.Y.Z crate version.
-- Lotus Version: The Lotus go.mod version.
+- 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
 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 | For every network upgrade (increase in Network Version)... | Versioning Scheme | Versioning Docs | go.mod direct dependencies | cargo.toml direct dependencies | Other direct dependencies
--- | -- | -- | -- | -- | -- | --
-`lotus` | There is at least one Lotus minor version. [^2] | 1.LOTUS_MINOR_VERSION.x | [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 `filecion-ffi` tracks `lotus`). | 1.LOTUS_MINOR_VERSION.x | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.ACTORS_VERSION.x | [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) | ACTORS_VERSION.0.x | [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. | FVM_ MAJOR_VERSION.y.x | [link](https://github.com/filecoin-project/ref-fvm?tab=readme-ov-file#versioning) | n/a | None | None
+| Repo | For every network upgrade (increase in Network Version)... | 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] | 1.<small>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 `filecion-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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
 
@@ -201,8 +203,6 @@ And you're done! These are all the steps necessary to create a network upgrade s
 
 You can take a look at this [Lotus PR as a reference](https://github.com/filecoin-project/lotus/pull/11964), which added the skeleton for network version 23.
 
-[^7]: 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.
-
 [^1]: Here is system.go template for a simple migration:
 
     ```go

From 85379250722a93ed0d958e1e916d62d98ce9b190 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Tue, 17 Sep 2024 14:15:46 -0700
Subject: [PATCH 03/11] formatting

---
 documentation/misc/Building_a_network_skeleton.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 00373734d0c..4fe83c0bcf4 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -25,8 +25,8 @@ There are these versions at play for a network upgrade:
 ### Network Upgrade Dependency Relationships
 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 | For every network upgrade (increase in Network Version)... | Versioning Scheme | Versioning Docs | go.mod direct dependencies | cargo.toml direct dependencies | Other direct dependencies |
-| --- | -------------- | --- | --- | --- | --- | --- |
+| 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] | 1.<small>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 `filecion-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>ACTORS_VERSION.x</small> | [link](https://github.com/filecoin-project/go-state-types?tab=readme-ov-file#versioning) | None | n/a | None |

From 2f4de944f7e4f009a990113fc0f1535fc03c09c8 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Tue, 17 Sep 2024 14:26:07 -0700
Subject: [PATCH 04/11] added diagram

---
 .../misc/Building_a_network_skeleton.md       | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 4fe83c0bcf4..b27a70e2b5e 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -35,6 +35,26 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 
 [^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.
 
+```mermaid
+graph TD
+    lotus[lotus]
+    ffi[filecoin-ffi]
+    gst[go-state-types]
+    ba[builtin-actors]
+    fvm[ref-fvm]
+
+    lotus -->gst
+    lotus -->|via submodule| ffi
+    lotus -->|via pack script| ba
+
+    gst --> ba
+
+    ffi --> gst
+    ffi --> fvm
+
+    ba --> fvm
+```
+
 ## Setup
 
 1. Clone the [ref-fvm](https://github.com/filecoin-project/ref-fvm.git) repository.

From 74443ee63277772cb1092ef7c21231a42c154fd7 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Tue, 17 Sep 2024 14:27:33 -0700
Subject: [PATCH 05/11] Moved diagram up

---
 .../misc/Building_a_network_skeleton.md       | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index b27a70e2b5e..8f47d3f049a 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -23,18 +23,6 @@ There are these versions at play for a network upgrade:
 - Actor Version: The incrementing integer that is associated with a builtin-actors bundle.
 
 ### Network Upgrade Dependency Relationships
-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] | 1.<small>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 `filecion-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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.
-
 ```mermaid
 graph TD
     lotus[lotus]
@@ -55,6 +43,18 @@ graph TD
     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] | 1.<small>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 `filecion-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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
 
 1. Clone the [ref-fvm](https://github.com/filecoin-project/ref-fvm.git) repository.

From 160836a4073322182ce24358c8429ae25e56dfab Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 08:18:56 -0700
Subject: [PATCH 06/11] Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>
---
 LOTUS_RELEASE_FLOW.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/LOTUS_RELEASE_FLOW.md b/LOTUS_RELEASE_FLOW.md
index 0d82d8faab3..8c3296ac13d 100644
--- a/LOTUS_RELEASE_FLOW.md
+++ b/LOTUS_RELEASE_FLOW.md
@@ -71,7 +71,7 @@ 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. ([Learn more about how network upgrades relate to Lotus and its key dependencies.](./documentation/misc/Building_a_network_skeleton.md#context))
+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. 
 

From 92c6f37a73a7e71df4bff984de97861c3c91f648 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 08:23:12 -0700
Subject: [PATCH 07/11] Update
 documentation/misc/Building_a_network_skeleton.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>
---
 documentation/misc/Building_a_network_skeleton.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 8f47d3f049a..acbec2e3998 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -48,7 +48,7 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 | 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] | 1.<small>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 `filecion-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | None |
+| `filecoin-ffi` | There is at least one `filecoin-ffi` minor version (since `filecoin-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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 |

From f65d1ad3b670bc2b1df9784d7c35dfb2ca6e4db5 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 08:23:37 -0700
Subject: [PATCH 08/11] Update
 documentation/misc/Building_a_network_skeleton.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>
---
 documentation/misc/Building_a_network_skeleton.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index acbec2e3998..59a63d2f883 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -51,7 +51,7 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 | `filecoin-ffi` | There is at least one `filecoin-ffi` minor version (since `filecoin-ffi` tracks `lotus`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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 |
+| `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.
 

From e2e49ae41ec604ee6d66639219963969025df01e Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 08:23:48 -0700
Subject: [PATCH 09/11] Update
 documentation/misc/Building_a_network_skeleton.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>
---
 documentation/misc/Building_a_network_skeleton.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 59a63d2f883..17652f6b8f4 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -50,7 +50,7 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 | `lotus` | There is at least one `lotus` minor version. [^0] | 1.<small>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`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | 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) | 0.<small>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 |
+| `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.

From 8a2d8cb119dc0519e2c527bde3c8831ce0b2a727 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 11:49:47 -0700
Subject: [PATCH 10/11] Adding rust-filecoin-proofs-api and removing
 go-state-types dependency from ffi

---
 documentation/misc/Building_a_network_skeleton.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 17652f6b8f4..31da0cb1d66 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -30,6 +30,7 @@ graph TD
     gst[go-state-types]
     ba[builtin-actors]
     fvm[ref-fvm]
+    proofs[rust-filecoin-proofs-api]
 
     lotus -->gst
     lotus -->|via submodule| ffi
@@ -37,8 +38,8 @@ graph TD
 
     gst --> ba
 
-    ffi --> gst
     ffi --> fvm
+    ffi --> proofs
 
     ba --> fvm
 ```
@@ -48,7 +49,7 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 | 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] | 1.<small>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`). | 1.<small>LOTUS_MINOR_VERSION.x</small> | [link](https://github.com/filecoin-project/filecoin-ffi?tab=readme-ov-file#versioning) | `go-state-types` | `ref-fvm` | None |
+| `filecoin-ffi` | There is at least one `filecoin-ffi` minor version (since `filecoin-ffi` tracks `lotus`). | 1.<small>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) | 0.<small>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 |

From 3402e2e4908e92473d3ef9e06ce463bb85c635d3 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <biglep@filoz.org>
Date: Thu, 19 Sep 2024 11:51:40 -0700
Subject: [PATCH 11/11] typos

---
 documentation/misc/Building_a_network_skeleton.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/documentation/misc/Building_a_network_skeleton.md b/documentation/misc/Building_a_network_skeleton.md
index 31da0cb1d66..d533788ec65 100644
--- a/documentation/misc/Building_a_network_skeleton.md
+++ b/documentation/misc/Building_a_network_skeleton.md
@@ -48,9 +48,9 @@ The table below gives an overview of how Lotus and its critical dependencies rel
 
 | 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] | 1.<small>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`). | 1.<small>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) | 0.<small>ACTORS_VERSION.x</small> | [link](https://github.com/filecoin-project/go-state-types?tab=readme-ov-file#versioning) | None | n/a | None |
+| `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 |