changelog pending and upgrading

CHANGELOG_PENDING.md

@@ -1,8 +1,15 @@
 ## v0.28.0
 
-*TBD*
+*January 14th, 2019*
 
 Special thanks to external contributors on this release:
+@fmauricios, @gianfelipe93, @husio, @needkane, @srmo, @yutianwu
+
+This release is primarily about upgrades to the `privval` system -
+separating the `priv_validator.json` into distinct config and data files, and
+refactoring the socket validator to support reconnections.
+
+See [UPGRADING.md](UPGRADING.md) for more details.
 
 ### BREAKING CHANGES:
 
@@ -10,14 +17,14 @@ Special thanks to external contributors on this release:
 - [cli] Removed `node` `--proxy_app=dummy` option. Use `kvstore` (`persistent_kvstore`) instead.
 - [cli] Renamed `node` `--proxy_app=nilapp` to `--proxy_app=noop`.
 - [config] \#2992 `allow_duplicate_ip` is now set to false
-- [privval] \#2926 split up `PubKeyMsg` into `PubKeyRequest` and `PubKeyResponse` to be consistent with other message types
+- [privval] \#1181 Split immutable and mutable parts of `priv_validator.json`
-- [privval] \#2923 listen for unix socket connections instead of dialing them
+  (@yutianwu)
+- [privval] \#2926 Split up `PubKeyMsg` into `PubKeyRequest` and `PubKeyResponse` to be consistent with other message types
+- [privval] \#2923 Listen for unix socket connections instead of dialing them
 
 * Apps
 
 * Go API
-- [types] \#2926 memoize consensus public key on initialization of remote signer and return the memoized key on
-`PrivValidator.GetPubKey()` instead of requesting it again
 - [types] \#2981 Remove `PrivValidator.GetAddress()`
 
 * Blockchain Protocol
@@ -25,16 +32,21 @@ Special thanks to external contributors on this release:
 * P2P Protocol
 
 ### FEATURES:
-- [privval] \#1181 Split immutable and mutable parts of `priv_validator.json`
+- [rpc] \#3052 Include peer's remote IP in `/net_info`
 
 ### IMPROVEMENTS:
-- [p2p/conn] \#3111 make SecretConnection thread safe
+- [consensus] \#3086 Log peerID on ignored votes (@srmo)
-- [privval] \#2923 retry RemoteSigner connections on error
+- [docs] \#3061 Added spec on signing consensus msgs at
-- [rpc] \#3047 Include peer's remote IP in `/net_info`
+  ./docs/spec/consensus/signing.md
+- [privval] \#2948 Memoize pubkey so it's only requested once on startup
+- [privval] \#2923 Retry RemoteSigner connections on error
 
 ### BUG FIXES:
 
-- [types] \#2926 do not panic if retrieving the private validator's public key fails
+- [types] \#2926 Do not panic if retrieving the private validator's public key fails
-- [rpc] \#3080 check if the variable "skipCount" is bigger than zero. If it is not, we set it to 0. If it, we do not do anything.
+- [rpc] \#3053 Fix internal error in `/tx_search` when results are empty
-- [crypto/multisig] \#3102 fix multisig keys address length
+  (@gianfelipe93)
+- [crypto/multisig] \#3102 Fix multisig keys address length
 - [crypto/encoding] \#3101 Fix `PubKeyMultisigThreshold` unmarshalling into `crypto.PubKey` interface
+- [build] \#3085 Fix `Version` field in build scripts (@husio)
+- [p2p/conn] \#3111 Make SecretConnection thread safe

UPGRADING.md

@@ -3,6 +3,56 @@
 This guide provides steps to be followed when you upgrade your applications to
 a newer version of Tendermint Core.
 
+## v0.28.0
+
+This release breaks the format for the `priv_validator.json` file
+and the protocol used for the external validator process.
+It is compatible with v0.27.0 blockchains (neither the BlockProtocol or the
+P2PProtocol have changed).
+
+Please read carefully for details about upgrading.
+
+XXX: Backup your `config/priv_validator.json`
+before proceeding.
+
+### `priv_validator.json`
+
+The `config/priv_validator.json` is now two files:
+`config/priv_validator_key.json` and `data/priv_validator_state.json`.
+The former contains the key material, the later contains the details on the last
+thing signed.
+
+When running v0.28.0 for the first time, it will back up any pre-existing
+`priv_validator.json` file and proceed to split it into the two new files.
+Upgrading should happen automatically without problem.
+
+To upgrade manually, use the provided `privValUpgrade.go` script, with exact paths for the old
+`priv_validator.json` and the locations for the two new files. It's recomended
+to use the default paths, of `config/priv_validator_key.json` and
+`data/priv_validator_state.json`, respectively:
+
+```
+go run scripts/privValUpgrade.go <old-path> <new-key-path> <new-state-path>
+```
+
+### External validator signers
+
+The Unix and TCP implementations of the remote signing validator
+have been consolidated into a single implementation.
+Thus in both cases, the external process is expected to dial
+Tendermint. This is different from how Unix sockets used to work, where
+Tendermint dialed the external process.
+
+The `PubKeyMsg` was also split into two for consistency with other message
+types.
+
+Note that the TCP sockets don't yet use a persistent key,
+so while they're encrypted, they can't yet be properly authenticated.
+See [#3105](https://github.com/tendermint/tendermint/issues/3105).
+Note the Unix socket has neither encryption nor authentication, but will
+add a shared-secret in [#3099](https://github.com/tendermint/tendermint/issues/3099).
+
+
 ## v0.27.0
 
 This release contains some breaking changes to the block and p2p protocols,