From 62838eb8cfdba0233577117b59c4cb2b0e3285f6 Mon Sep 17 00:00:00 2001
From: Julien Robert <julien@rbrt.fr>
Date: Wed, 13 Sep 2023 23:42:17 +0200
Subject: [PATCH] docs: improve upgrade docs on preblocker (#17734)

---
 UPGRADING.md                                  | 29 ++++++++++++---
 .../build/building-apps/03-app-upgrade.md     | 36 +++++++------------
 x/upgrade/README.md                           |  2 +-
 3 files changed, 38 insertions(+), 29 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index 3b4c55587b..d8e858b939 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -104,20 +104,41 @@ for more info.
 
 #### Set PreBlocker
 
-**Users using `depinject` / app v2 do not need any changes, this is abstracted for them.**
+A `SetPreBlocker` method has been added to BaseApp. This is essential for BaseApp to run `PreBlock` which runs before begin blocker other modules, and allows to modify consensus parameters, and the changes are visible to the following state machine logics.
+Read more about other use cases [here](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-068-preblock.md).
+
+`depinject` / app v2 users need to add `x/upgrade` in their `app_config.go` / `app.yml`:
 
 ```diff
-+ app.SetPreBlocker(app.PreBlocker)
++ PreBlockers: []string{
++	upgradetypes.ModuleName,
++ },
+BeginBlockers: []string{
+-	upgradetypes.ModuleName,
+	minttypes.ModuleName,
+}
 ```
 
+When using (legacy) application wiring, the following must be added to `app.go`:
+
 ```diff
++app.ModuleManager.SetOrderPreBlockers(
++	upgradetypes.ModuleName,
++)
+
+app.ModuleManager.SetOrderBeginBlockers(
+-	upgradetypes.ModuleName,
+)
+
++ app.SetPreBlocker(app.PreBlocker)
+
+// ... //
+
 +func (app *SimApp) PreBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (sdk.ResponsePreBlock, error) {
 +	return app.ModuleManager.PreBlock(ctx, req)
 +}
 ```
 
-BaseApp added `SetPreBlocker` for apps. This is essential for BaseApp to run `PreBlock` which runs before begin blocker other modules, and allows to modify consensus parameters, and the changes are visible to the following state machine logics.
-
 #### Events
 
 The log section of `abci.TxResult` is not populated in the case of successful
diff --git a/docs/docs/build/building-apps/03-app-upgrade.md b/docs/docs/build/building-apps/03-app-upgrade.md
index c0e83555aa..f59dff94ca 100644
--- a/docs/docs/build/building-apps/03-app-upgrade.md
+++ b/docs/docs/build/building-apps/03-app-upgrade.md
@@ -50,34 +50,22 @@ the rest of the block as normal. Once 2/3 of the voting power has upgraded, the
 resume the consensus mechanism. If the majority of operators add a custom `do-upgrade` script, this should
 be a matter of minutes and not even require them to be awake at that time.
 
-## Set PreBlocker
-
-:::tip
-Users using `depinject` / app v2 do not need any changes, this is abstracted for them.
-:::
-
-Call `SetPreBlocker` to run `PreBlock`:
-
-```go
-app.SetPreBlocker(app.PreBlocker)
-```
-
-```go
-func (app *SimApp) PreBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (sdk.ResponsePreBlock, error) {
-	return app.ModuleManager.PreBlock(ctx, req)
-}
-```
-
 ## Integrating With An App
 
-Setup an upgrade Keeper for the app and then define a `BeginBlocker` that calls the upgrade
-keeper's BeginBlocker method:
+::tip
+The following is not required for users using `depinject` / app v2, this is abstracted for them.
+::
+
+In addition to basic module wiring, setup the upgrade Keeper for the app and then define a `PreBlocker` that calls the upgrade
+keeper's PreBlocker method:
 
 ```go
- func (app *myApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (abci.ResponseBeginBlock, error) {
-  app.upgradeKeeper.BeginBlocker(ctx, req)
-  return abci.ResponseBeginBlock{}, nil
- }
+func (app *myApp) PreBlocker(ctx sdk.Context, req req.RequestFinalizeBlock) (sdk.ResponsePreBlock, error) {
+      // For demonstration sake, the app PreBlocker only returns the upgrade module pre-blocker.
+      // In a real app, the module manager should call all pre-blockers
+      // return return app.ModuleManager.PreBlock(ctx, req)
+      return app.upgradeKeeper.PreBlocker(ctx, req)
+}
 ```
 
 The app must then integrate the upgrade keeper with its governance module as appropriate. The governance module
diff --git a/x/upgrade/README.md b/x/upgrade/README.md
index 698e822ba8..0d98c1601e 100644
--- a/x/upgrade/README.md
+++ b/x/upgrade/README.md
@@ -8,7 +8,7 @@ sidebar_position: 1
 
 `x/upgrade` is an implementation of a Cosmos SDK module that facilitates smoothly
 upgrading a live Cosmos chain to a new (breaking) software version. It accomplishes this by
-providing a `BeginBlocker` hook that prevents the blockchain state machine from
+providing a `PreBlocker` hook that prevents the blockchain state machine from
 proceeding once a pre-defined upgrade block height has been reached.
 
 The module does not prescribe anything regarding how governance decides to do an