docs: clarify differences and usage of submit-proposal and `submit-…

…legacy-proposal` for gov (#12410) (#12470)

CHANGELOG.md

@@ -209,7 +209,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
 * [\#9594](https://github.com/cosmos/cosmos-sdk/pull/9594) Remove legacy REST API. Please see the [REST Endpoints Migration guide](https://docs.cosmos.network/master/migrations/rest.html) to migrate to the new REST endpoints.
 * [\#9995](https://github.com/cosmos/cosmos-sdk/pull/9995) Increased gas cost for creating proposals.
 * [\#11029](https://github.com/cosmos/cosmos-sdk/pull/11029) The deprecated Vote Option field is removed in gov v1beta2 and nil in v1beta1. Use Options instead.
-* [\#11013](https://github.com/cosmos/cosmos-sdk/pull/) The `tx gov submit-proposal` command has changed syntax to support the new Msg-based gov proposals. To access the old CLI command, please use `tx gov submit-legacy-proposal`.
+* [\#11013](https://github.com/cosmos/cosmos-sdk/pull/11013) The `tx gov submit-proposal` command has changed syntax to support the new Msg-based gov proposals. To access the old CLI command, please use `tx gov submit-legacy-proposal`.
 * [\#11170](https://github.com/cosmos/cosmos-sdk/issues/11170) Fixes issue related to grpc-gateway of supply by ibc-denom.
 
 ### CLI Breaking Changes

x/gov/spec/01_concepts.md

@@ -177,7 +177,7 @@ Later, we may add permissioned keys that could only sign txs from certain module
 
 If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade
 their software to the new version that was voted. This process is divided into
-two steps.
+two steps:
 
 ### Signal
 
@@ -200,4 +200,4 @@ Once a block contains more than 2/3rd _precommits_ where a common
 nodes, non-validating full nodes and light-nodes) are expected to switch to the
 new version of the software.
 
-_Note: Not clear how the flip is handled programmatically._
+Validators and full nodes can use an automation tool, such as [Cosmovisor](https://github.com/cosmos/cosmos-sdk/blob/main/cosmovisor/README.md), for automatically switching version of the chain.

x/gov/spec/02_state.md

@@ -16,11 +16,11 @@ unique id and contains a series of timestamps: `submit_time`, `deposit_end_time`
 
 A proposal will generally require more than just a set of messages to explain its
 purpose but need some greater justification and allow a means for interested participants
-to discuss and debate the proposal. In most cases, it is encouraged to have an off-chain
-system that supports the on-chain governance process. To accommodate for this, a
-proposal contains a special `metadata` field, an array of bytes, which can be used to
-add context to the proposal. The `metadata` field allows custom use for networks, however,
-it is expected that the field contains a URL or some form of CID using a system such as
+to discuss and debate the proposal.
+In most cases, **it is encouraged to have an off-chain system that supports the on-chain governance process**.
+To accommodate for this, a proposal contains a special **`metadata`** field, an array of bytes,
+which can be used to add context to the proposal. The `metadata` field allows custom use for networks,
+however, it is expected that the field contains a URL or some form of CID using a system such as
 [IPFS](https://docs.ipfs.io/concepts/content-addressing/). To support the case of
 interoperability across networks, the SDK recommends that the `metadata` represents
 the following `JSON` template:
@@ -37,7 +37,7 @@ the following `JSON` template:
 This makes it far easier for clients to support multiple networks.
 
 The metadata has a maximum length that is chosen by the app developer, and
-passed into the gov keeper as a config.
+passed into the gov keeper as a config. The default maximum length in the SDK is 255 characters.
 
 ### Writing a module that uses governance
 
@@ -119,8 +119,7 @@ This type is used in a temp map when tallying
 
 ## Stores
 
-_Stores are KVStores in the multi-store. The key to find the store is the first
-parameter in the list_`
+_Note: Stores are KVStores in the multi-store. The key to find the store is the first parameter in the list_
 
 We will use one KVStore `Governance` to store two mappings:
 
@@ -206,3 +205,13 @@ And the pseudocode for the `ProposalProcessingQueue`:
 
       store(Governance, <proposalID|'proposal'>, proposal)
 ```
+
+## Legacy Proposal
+
+A legacy proposal is the old implementation of governance proposal.
+Contrary to proposal that can contain any messages, a legacy proposal allows to submit a set of pre-defined proposals.
+These proposal are defined by their types.
+
+While proposals should use the new implementation of the governance proposal, we need still to use legacy proposal in order to submit a `software-upgrade` and a `cancel-software-upgrade` proposal.
+
+More information on how to submit proposals in the [client section](07_client.md).

x/gov/spec/07_client.md

@@ -361,14 +361,14 @@ Example:
 simd tx gov submit-proposal /path/to/proposal.json --from cosmos1..
 ```
 
-where proposal.json contains:
+where `proposal.json` contains:
 
-```bash
+```json
 {
   "messages": [
     {
       "@type": "/cosmos.bank.v1beta1.MsgSend",
-      "from_address": "cosmos1...",
+      "from_address": "cosmos1...", // The gov module module address
       "to_address": "cosmos1...",
       "amount":[{"denom": "stake","amount": "10"}]
     }