diff --git a/api/api_common.go b/api/api_common.go
index b1aaa4a82..2f27eb95f 100644
--- a/api/api_common.go
+++ b/api/api_common.go
@@ -15,6 +15,17 @@ import (
 	apitypes "github.com/filecoin-project/lotus/api/types"
 )
 
+//                       MODIFYING THE API INTERFACE
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 type Common interface {
 
 	// MethodGroup: Auth
diff --git a/api/api_full.go b/api/api_full.go
index c6d328934..a90b0c89f 100644
--- a/api/api_full.go
+++ b/api/api_full.go
@@ -41,6 +41,20 @@ type ChainIO interface {
 
 const LookbackNoLimit = abi.ChainEpoch(-1)
 
+//                       MODIFYING THE API INTERFACE
+//
+// NOTE: This is the V1 (Unstable) API - to add methods to the V0 (Stable) API
+// you'll have to add those methods to interfaces in `api/v0api`
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 // FullNode API is a low-level interface to the Filecoin network full node
 type FullNode interface {
 	Common
diff --git a/api/api_gateway.go b/api/api_gateway.go
index 08b3e0681..130a18c55 100644
--- a/api/api_gateway.go
+++ b/api/api_gateway.go
@@ -14,6 +14,20 @@ import (
 	"github.com/filecoin-project/lotus/chain/types"
 )
 
+//                       MODIFYING THE API INTERFACE
+//
+// NOTE: This is the V1 (Unstable) API - to add methods to the V0 (Stable) API
+// you'll have to add those methods to interfaces in `api/v0api`
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 type Gateway interface {
 	ChainHasObj(context.Context, cid.Cid) (bool, error)
 	ChainHead(ctx context.Context) (*types.TipSet, error)
diff --git a/api/api_storage.go b/api/api_storage.go
index 9662e8cd8..1131f45a0 100644
--- a/api/api_storage.go
+++ b/api/api_storage.go
@@ -26,6 +26,17 @@ import (
 	"github.com/filecoin-project/lotus/extern/sector-storage/storiface"
 )
 
+//                       MODIFYING THE API INTERFACE
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 // StorageMiner is a low-level interface to the Filecoin network storage miner node
 type StorageMiner interface {
 	Common
diff --git a/api/api_worker.go b/api/api_worker.go
index 3232de449..e834b792c 100644
--- a/api/api_worker.go
+++ b/api/api_worker.go
@@ -14,6 +14,17 @@ import (
 	"github.com/filecoin-project/specs-storage/storage"
 )
 
+//                       MODIFYING THE API INTERFACE
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 type Worker interface {
 	Version(context.Context) (Version, error) //perm:admin
 
diff --git a/api/v0api/full.go b/api/v0api/full.go
index db5f847bf..35100f032 100644
--- a/api/v0api/full.go
+++ b/api/v0api/full.go
@@ -26,6 +26,23 @@ import (
 
 //go:generate go run github.com/golang/mock/mockgen -destination=v0mocks/mock_full.go -package=v0mocks . FullNode
 
+//                       MODIFYING THE API INTERFACE
+//
+// NOTE: This is the V0 (Stable) API - when adding methods to this interface,
+// you'll need to make sure they are also present on the V1 (Unstable) API
+//
+// This API is implemented in `v1_wrapper.go` as a compatibility layer backed
+// by the V1 api
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 // FullNode API is a low-level interface to the Filecoin network full node
 type FullNode interface {
 	Common
diff --git a/api/v0api/gateway.go b/api/v0api/gateway.go
index 603c099e8..8a55b4c27 100644
--- a/api/v0api/gateway.go
+++ b/api/v0api/gateway.go
@@ -15,6 +15,23 @@ import (
 	"github.com/filecoin-project/lotus/chain/types"
 )
 
+//                       MODIFYING THE API INTERFACE
+//
+// NOTE: This is the V0 (Stable) API - when adding methods to this interface,
+// you'll need to make sure they are also present on the V1 (Unstable) API
+//
+// This API is implemented in `v1_wrapper.go` as a compatibility layer backed
+// by the V1 api
+//
+// When adding / changing methods in this file:
+// * Do the change here
+// * Adjust implementation in `node/impl/`
+// * Run `make gen` - this will:
+//  * Generate proxy structs
+//  * Generate mocks
+//  * Generate markdown docs
+//  * Generate openrpc blobs
+
 type Gateway interface {
 	ChainHasObj(context.Context, cid.Cid) (bool, error)
 	ChainHead(ctx context.Context) (*types.TipSet, error)