chore: cosmovisor/v1.0.0 release notes (cosmos#10266)

* chore: cosmovisor/v1.0.0 release notes

* adding a link

* markdown linting

cosmovisor/CHANGELOG.md

@@ -29,18 +29,18 @@ Types of changes (Stanzas):
 "Client Breaking" for breaking Protobuf, gRPC and REST routes used by end-users.
 "CLI Breaking" for breaking CLI commands.
 "API Breaking" for breaking exported APIs used by developers building on SDK.
-"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList.
 Ref: https://keepachangelog.com/en/1.0.0/
 -->
 
 # Changelog
 
 ## [Unreleased]
 
+## v1.0.0 2021-09-30
+
 ### Features
 
 + [\#8590](https://github.com/cosmos/cosmos-sdk/pull/8590) File watcher for cosmovisor. Instead of parsing logs from stdin and stderr, we watch the `<DAEMON_HOME>/data/upgrade-info.json` file updates using polling mechanism.
-+ [\#10128](https://github.com/cosmos/cosmos-sdk/pull/10128) Change default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
 + [\#9999](https://github.com/cosmos/cosmos-sdk/pull/10103) Added `version` command that returns the cosmovisor version and the application version.
 + [\#9973](https://github.com/cosmos/cosmos-sdk/pull/10056) Added support for pre-upgrade command in Cosmovisor to be called before the binary is upgraded. Added new environmental variable `DAEMON_PREUPGRADE_MAX_RETRIES` that holds the maximum number of times to reattempt pre-upgrade before failing.
 + [\#10126](https://github.com/cosmos/cosmos-sdk/pull/10229) Added `help`.
@@ -51,6 +51,9 @@ Ref: https://keepachangelog.com/en/1.0.0/
 + [\#10036](https://github.com/cosmos/cosmos-sdk/pull/10036) Improve logs when downloading the binary.
 + [\#10217](https://github.com/cosmos/cosmos-sdk/pull/10217) Replacing logging to use zerolog.
 
+### CLI Breaking
++ [\#10128](https://github.com/cosmos/cosmos-sdk/pull/10128) Change default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
+
 ## v0.1 2021-08-06
 
 This is the first release and we started this changelog on 2021-07-01. See the (README)[https://github.com/cosmos/cosmos-sdk/blob/release/cosmovisor/v0.1.x/cosmovisor/CHANGELOG.md] file for the full list of features.

cosmovisor/README.md

@@ -5,13 +5,14 @@
 #### Design
 
 Cosmovisor is designed to be used as a wrapper for an `Cosmos SDK` app:
-* it will pass all arguments to the app. Running `cosmovisor arg1 arg2 ....` will run `app arg1 arg2 ...`;
+* it will pass all arguments to the associated app (configured by `DAEMON_NAME` env variable).
+  Running `cosmovisor arg1 arg2 ....` will run `app arg1 arg2 ...`;
 * it will manage an app by restarting and upgrading if needed;
 * it is configured using environment variables, not positional arguments.
 
 *Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting `cosmovisor` with the new binary. For this reason, we recommend applications adopt in-place store migrations.*
 
-*Note: If validators would like to enable the auto-download option, and they are currently running an application using Cosmos SDK `v0.42`, they will need to use Cosmovisor [`v0.1`](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv0.1.0). Later versions of Cosmovisor do not support Cosmos SDK `v0.42` or earlier if the auto-download option is enabled.*
+*Note: If validators would like to enable the auto-download option (which [we don't recommend](#auto-download)), and they are currently running an application using Cosmos SDK `v0.42`, they will need to use Cosmovisor [`v0.1`](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv0.1.0). Later versions of Cosmovisor do not support Cosmos SDK `v0.42` or earlier if the auto-download option is enabled.*
 
 ## Contributing
 
@@ -43,7 +44,7 @@ All arguments passed to `cosmovisor` will be passed to the application binary (a
 * `DAEMON_RESTART_AFTER_UPGRADE` (*optional*, default = `true`), if `true`, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (`false`), `cosmovisor` stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs.
 * `DAEMON_POLL_INTERVAL` is the interval length in milliseconds for polling the upgrade plan file. Default: 300.
 * `UNSAFE_SKIP_BACKUP` (defaults to `false`), if set to `false`, backs up the data before trying the upgrade. Otherwise (`true`), upgrades directly without performing a backup. The default value of false is useful and recommended in case of failures and when a backup needed to rollback. We recommend using the default backup option `UNSAFE_SKIP_BACKUP=false`.
-* `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call `pre-upgrade` in the application after exit status of `31`. After the maximum number of retries, cosmovisor fails the upgrade. 
+* `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call `pre-upgrade` in the application after exit status of `31`. After the maximum number of retries, cosmovisor fails the upgrade.
 
 
 ### Folder Layout
@@ -92,12 +93,12 @@ The `DAEMON` specific code and operations (e.g. tendermint config, the applicati
 
 ### Commands
 
-Because Cosmovisor is meant to be used as a wrapper for a Cosmos SDK application, it does not require many commands. 
+Because Cosmovisor is meant to be used as a wrapper for a Cosmos SDK application, it does not require many commands.
 
 To determine the version of Cosmovisor, run the following command:
 ```
 cosmovisor version
-``` 
+```
 The output of the `cosmovisor version` command shows the version of the Cosmos SDK application and the version of Cosmovisor:
 
 ```
@@ -115,13 +116,17 @@ The following heuristic is applied to detect the upgrade:
 + If `cosmovisor/current/upgrade-info.json` doesn't exist but `data/upgrade-info.json` exists, then `cosmovisor` assumes that whatever is in `data/upgrade-info.json` is a valid upgrade request. In this case `cosmovisor` tries immediately to make an upgrade according to the `name` attribute in `data/upgrade-info.json`.
 + Otherwise, `cosmovisor` waits for changes in `upgrade-info.json`. As soon as a new upgrade name is recorded in the file, `cosmovisor` will trigger an upgrade mechanism.
 
-When the upgrade mechanism is triggered, `cosmovisor` will start by auto-downloading a new binary (if `DAEMON_ALLOW_DOWNLOAD_BINARIES` is enabled) into `cosmovisor/<name>/bin` (where `<name>` is the `upgrade-info.json:name` attribute). `cosmovisor` will then update the `current` symbolic link to point to the new directory and save `data/upgrade-info.json` to `cosmovisor/current/upgrade-info.json`.
+When the upgrade mechanism is triggered, `cosmovisor` will:
+1. if `DAEMON_ALLOW_DOWNLOAD_BINARIES` is enabled, start by auto-downloading a new binary into `cosmovisor/<name>/bin` (where `<name>` is the `upgrade-info.json:name` attribute);
+2. update the `current` symbolic link to point to the new directory and save `data/upgrade-info.json` to `cosmovisor/current/upgrade-info.json`.
 
 ### Auto-Download
 
-Generally, `cosmovisor` requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an easier setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option.
+Generally, `cosmovisor` requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an automated setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option.
+
+**NOTE: we don't recommend using auto-download** because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart an App (which could lead to a chain halt).
 
-If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself. The plan stored in the upgrade module has an info field for arbitrary JSON. This info is expected to be outputed on the halt log message. There are two valid formats to specify a download in such a message:
+If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself based on the instructions in the `info` attribute in the `data/upgrade-info.json` file. The files is constructed by the x/upgrade module and contains data from the upgrade `Plan` object. The `Plan` has an info field that is expected to have one of the following two valid formats to specify a download:
 
 1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key. For example:
 

cosmovisor/RELEASE_NOTES.md

@@ -1,8 +1,33 @@
-# Cosmovisor v0.1.0 Release Notes
+# Cosmovisor v1.0.0 Release Notes
 
-This is the first tracked release of Cosmovisor. It contains the original behavior of scanning app stdin and stdout.
-Since the original design, this release contains one important feature: state backup. Since v0.1, by default, cosmovisor will make a state backup (`<app_directory>/data` directory). Backup will be skipped if `UNSAFE_SKIP_BACKUP=true` is set.
+This is the first major release of Cosmovisor.
+It changes the way Cosmovisor is searching for an upgrade event from an app.
+Instead of scanning standard input and standard output logs, the Cosmovisor
+observes the `$DAEMON_HOME/upgrade-info.json` file, that is produced by the
+`x/upgrade` module. The `upgrade-info.json` files is created by the `x/upgrade`
+module and contains information from the on-chain upgrade Plan record.
+Using the file based approach solved many outstanding problems: freezing when
+logs are too long, race condition with the `x/upgrade` handler, and potential
+exploit (if a chain would allow to log an arbitrary message, then an attacker
+could produce a fake upgrade signal and halt a chain or instrument a download
+of modified, hacked binary when the auto download option is enabled).
 
-Updates to this release will be pushed to `release/cosmovisor/v0.1.x` branch.
+## Auto downloads
 
-Please see the [CHANGELOG](https://github.com/cosmos/cosmos-sdk/blob/release/cosmovisor/v0.1.x/cosmovisor/CHANGELOG.md) for more details.
+Cosmovisor v1.0 supports auto downloads based on the information in the
+`data/upgrade-info.json`. In the Cosmos SDK `< v0.44`, that file doesn't contain
+`upgrade.Plan.Info`, that is needed for doing auto download. Hence Cosmovisor `v1.0`
+auto download won't work with Apps updating from `v0.43` and earlier.
+
+NOTE: we **don't recommend using auto download** functionality. It can lead to potential
+chain halt when the upgrade Plan contains a bad link or the resource with the
+binary will be temporarily unavailable. We are planning on adding a upgrade
+verification command which can potentially solve this issue.
+
+## Other updates
+
++ Changed default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
++ Added `version` command, which prints both the Cosmovisor and the associated app version.
++ Added `help`  command, which prints the Cosmovisor help without passing it to the associated version. This is an exception, because normally, Cosmovisor passes all arguments to the associated app.
+
+For more details, please see the [CHANGELOG](https://github.com/cosmos/cosmos-sdk/blob/cosmovisor/v1.0.0/cosmovisor/CHANGELOG.md).