docs: improve upgrade docs on preblocker (#17734)

(cherry picked from commit 62838eb)

Author: julienrbrt

UPGRADING.md

@@ -69,20 +69,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

docs/docs/build/building-apps/03-app-upgrade.md

@@ -50,36 +50,24 @@ 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.
-:::
+## Integrating With An App
 
-Call `SetPreBlocker` to run `PreBlock`:
+::tip
+The following is not required for users using `depinject` / app v2, this is abstracted for them.
+::
 
-```go
-app.SetPreBlocker(app.PreBlocker)
-```
+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 *SimApp) PreBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (sdk.ResponsePreBlock, error) {
-	return app.ModuleManager.PreBlock(ctx, req)
+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)
 }
 ```
 
-## Integrating With An App
-
-Setup an upgrade Keeper for the app and then define a `BeginBlocker` that calls the upgrade
-keeper's BeginBlocker method:
-
-```go
- func (app *myApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (abci.ResponseBeginBlock, error) {
-  app.upgradeKeeper.BeginBlocker(ctx, req)
-  return abci.ResponseBeginBlock{}, nil
- }
-```
-
 The app must then integrate the upgrade keeper with its governance module as appropriate. The governance module
 should call ScheduleUpgrade to schedule an upgrade and ClearUpgradePlan to cancel a pending upgrade.
 

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