update UPGRADING.md and minor docs fixes

CHANGELOG.md

@@ -9,9 +9,13 @@ peerlink, Ahmah2009, bluele, b00f.
 
 This release includes breaking upgrades in the block header,
 including the long awaited changes for delaying validator set updates by one
-block. It also fixes enforcement on the max size of blocks, and includes a BFT
+block to better support light clients.
-timestamp in each block that can be safely used by applications. There are also some
+It also fixes enforcement on the maximum size of blocks, and includes a BFT
-minor breaking changes to the rpc, config, and ABCI.
+timestamp in each block that can be safely used by applications.
+There are also some minor breaking changes to the rpc, config, and ABCI.
+
+See the [UPGRADING.md](UPGRADING.md#v0.24.0) for details on upgrading to the new
+version.
 
 From here on, breaking changes will be broken down to better reflect how users
 are affected by a change.
@@ -20,6 +24,8 @@ A few more breaking changes are in the works - each will come with a clear
 Architecture Decision Record (ADR) explaining the change. You can review ADRs
 [here](https://github.com/tendermint/tendermint/tree/develop/docs/architecture)
 or in the [open Pull Requests](https://github.com/tendermint/tendermint/pulls).
+You can also check in on the [issues marked as
+breaking](https://github.com/tendermint/tendermint/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking).
 
 BREAKING CHANGES:
 
@@ -84,6 +90,7 @@ FEATURES:
 
 IMPROVEMENTS:
 - [docs] Lint documentation with `write-good` and `stop-words`.
+- [docs] [\#2249](https://github.com/tendermint/tendermint/issues/2249) Refactor, deduplicate, and improve the ABCI docs and spec (with thanks to @ttmc).
 - [scripts] [\#2196](https://github.com/tendermint/tendermint/issues/2196) Added json2wal tool, which is supposed to help our users restore (@bradyjoestar)
   corrupted WAL files and compose test WAL files (@bradyjoestar)
 - [mempool] [\#2234](https://github.com/tendermint/tendermint/issues/2234) Now stores txs by hash inside of the cache, to mitigate memory leakage

UPGRADING.md

@@ -3,10 +3,11 @@
 This guide provides steps to be followed when you upgrade your applications to
 a newer version of Tendermint Core.
 
-## Upgrading from 0.23.0 to 0.24.0
+## v0.24.0
 
 New 0.24.0 release contains a lot of changes to the state and types. It's not
-compatible to the old versions.
+compatible to the old versions and there is no straight forward way to update
+old data to be compatible with the new version.
 
 To reset the state do:
 
@@ -14,6 +15,8 @@ To reset the state do:
 $ tendermint unsafe_reset_all
 ```
 
+Here we summarize some other notable changes to be mindful of.
+
 ### Config changes
 
 `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and
@@ -28,5 +31,32 @@ max_num_outbound_peers = 10
 ```
 
 As you can see, the default ratio of inbound/outbound peers is 4/1. The reason
-as we want it to be easier for new nodes to connect to the network. You can
+is we want it to be easier for new nodes to connect to the network. You can
 tweak these parameters to alter the network topology.
+
+### RPC Changes
+
+The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field.
+
+### ABCI Changes
+
+The header has been upgraded and contains new fields, but none of the existing
+fields were changed, except their order.
+
+The `Validator` type was split into two, one containing an `Address` and one
+containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator`
+type, which contains just the `Address`. When returning `ResponseEndBlock`, use
+the `ValidatorUpdate` type, which contains just the `PubKey`.
+
+### Validator Set Updates
+
+Validator set updates returned in ResponseEndBlock for height `H` used to take
+effect immediately at height `H+1`. Now they will be delayed one block, to take
+effect at height `H+2`. Note this means that the change will be seen by the ABCI
+app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`.
+
+### Block Size
+
+The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of
+`ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks
+are limitted only by byte-size, not by number of transactions.

docs/spec/software/abci.md

@@ -1,3 +1,3 @@
 # Application Blockchain Interface (ABCI)
 
-This page has [moved](../spec/abci/apps.md).
+This page has [moved](../abci/apps.md).