feat: adding pre-upgrade command call in Cosmovisor (#10056)

Cosmosvisor calls pre-upgrade command on the application before upgrade

docs/migrations/README.md

@@ -9,6 +9,7 @@ parent:
 This folder contains all the migration guides to update your app and modules to Cosmos v0.40 Stargate.
 
 1. [App and Modules Migration](./app_and_modules.md)
+1. [Pre Upgrade](./pre-upgrade.md)
 1. [Chain Upgrade Guide to v0.40](./chain-upgrade-guide-040.md)
 1. [REST Endpoints Migration](./rest.md)
 1. [Keyring Migration](./keyring.md)

docs/migrations/pre-upgrade.md

@@ -0,0 +1,57 @@
+# Pre-Upgrade Handling
+
+Cosmovisor supports custom pre-upgrade handling. Use pre-upgrade handling when you need to implement application config changes that are required in the newer version before you perform the upgrade.
+
+Using Cosmovisor pre-upgrade handling is optional. If pre-upgrade handling is not implemented, the upgrade continues.
+
+For example, make the required new-version changes to `app.toml` settings during the pre-upgrade handling. The pre-upgrade handling process means that the file does not have to be manually updated after the upgrade.
+
+Before the application binary is upgraded, Cosmovisor calls a `pre-upgrade` command that can  be implemented by the application.
+
+The `pre-upgrade` command does not take in any command-line arguments and is expected to terminate with the following exit codes:
+
+
+| Exit status code | How it is handled in Cosmosvisor                                                                                    |
+|------------------|---------------------------------------------------------------------------------------------------------------------|
+| `0`              | Assumes `pre-upgrade` command executed successfully and continues the upgrade.                                      |
+| `1`              | Default exit code when `pre-upgrade` command has not been implemented.                                              |
+| `30`             | `pre-upgrade` command was executed but failed. This fails the entire upgrade.                                       |
+| `31`             | `pre-upgrade` command was executed but failed. But the command is retried until exit code `1` or `30` are returned. |
+
+
+## Sample
+
+Here is a sample structure of the `pre-upgrade` command:
+
+```go
+func preUpgradeCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "pre-upgrade",
+		Short: "Pre-upgrade command",
+        Long: "Pre-upgrade command to implement custom pre-upgrade handling",
+		Run: func(cmd *cobra.Command, args []string) {
+
+			err := HandlePreUpgrade()
+
+			if err != nil {
+				os.Exit(30)
+			}
+
+			os.Exit(0)
+
+		},
+	}
+
+	return cmd
+}
+```
+
+
+Ensure that the pre-upgrade command has been registered in the application:
+```go
+rootCmd.AddCommand(
+		// ..
+		preUpgradeCommand(),
+		// ..
+	)
+```