Cleanup and standardize the READMEs (cometbft#482)

* changes.md -> changelog.md

* add and standardize readmes

* contrib link

* fix repo root link

* add detection link

* light-node badges

Author: ebuchman

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,4 +10,4 @@ changes in the PR.
 * [ ] Updated all relevant documentation in docs
 * [ ] Updated all code comments where relevant
 * [ ] Wrote tests
-* [ ] Updated CHANGES.md
+* [ ] Updated CHANGELOG.md

CHANGES.md renamed to CHANGELOG.md

@@ -56,7 +56,8 @@ of smaller incremental changes, in the form of small PRs that can be merged
 quickly. This helps manage the load for reviewers and reduces the likelihood
 that PRs will sit open for longer.
 
-![Contributing flow](./docs/imgs/contributing.png)
+![Contributing
+flow](https://github.com/tendermint/tendermint/blob/v0.33.6/docs/imgs/contributing.png)
 
 Each stage of the process is aimed at creating feedback cycles which align contributors and maintainers to make sure:
 
@@ -87,19 +88,24 @@ To pull in updates from the origin repo, run
 
 ## Changelog
 
-Every non-trivial PR must update the CHANGELOG.md.
+Every non-trivial PR must update the [CHANGELOG.md].
 
-Changes for a given release should be split between the four sections: Breaking
-Changes, Features, Improvements, Bug Fixes.
+Changelog structure is modeled after 
+[Tendermint
+Core](https://github.com/tendermint/tendermint/blob/master/CHANGELOG.md)
+and 
+[Hashicorp Consul](http://github.com/hashicorp/consul/tree/master/CHANGELOG.md).
+See those changelogs for examples.
 
-See the [changelog template](CHANGELOG.md). 
+Changes for a given release should be split between the five sections: Security, Breaking
+Changes, Features, Improvements, Bug Fixes.
 
 Changelog entries should be formatted as follows:
 ```
-- [crate] \#xxx Some description about the change (@contributor)
+- [pkg] \#xxx Some description about the change (@contributor)
 ```
-Here, `crate` is the part of the code that changed (typically a
-top-level crate), `xxx` is the pull-request number, and `contributor`
+Here, `pkg` is the part of the code that changed (typically a
+top-level crate, but could be <crate>/<module>), `xxx` is the pull-request number, and `contributor`
 is the author/s of the change.
 
 It's also acceptable for `xxx` to refer to the relevent issue number, but pull-request
@@ -108,7 +114,7 @@ Note this means pull-requests should be opened first so the changelog can then
 be updated with the pull-request's number.
 
 Changelog entries should be ordered alphabetically according to the
-`module`, and numerically according to the pull-request number.
+`pkg`, and numerically according to the pull-request number.
 
 Changes with multiple classifications should be doubly included (eg. a bug fix
 that is also a breaking change should be recorded under both).

CONTRIBUTING.md

@@ -5,36 +5,42 @@
 [![Build Status][build-image]][build-link]
 [![Audit Status][audit-image]][audit-link]
 [![Apache 2.0 Licensed][license-image]][license-link]
-![Rust 1.39+][rustc-image]
+![Rust 1.44+][rustc-image]
 
-Rust crates for interacting with [Tendermint]: a high-performance blockchain
-consensus engine that powers Byzantine fault tolerant applications written
-in any programming language.
+[Tendermint] in Rust with [TLA+ specifications](/docs/spec).
 
-Also includes [TLA+ specifications](/docs/spec).
+Tendermint is a high-performance blockchain consensus engine 
+for Byzantine fault tolerant applications written in any programming language.
 
-## Releases
+## Requirements
+
+Tested with Rust 1.44+, may work on older version.
+
+Compatible with the v0.33 series of [Tendermint Core][Tendermint].
+
+## Documentation
 
-Release tags can be found on
-[Github](https://github.com/informalsystems/tendermint-rs/releases).
+See each component for the relevant documentation.
 
-Releases for each crate are published to crates.io:
+Libraries:
 
-- [tendermint][tendermint-docs-link] - Tendermint data structures and
+- [tendermint](./tendermint) - Tendermint data structures and
   serialization
-- [tendermint-rpc][tendermint-rpc-docs-link] - Tendermint RPC client and
+- [tendermint-rpc](./rpc) - Tendermint RPC client and
   response types
-- [light-client][tendermint-light-client-docs-link] - Tendermint light client library for verifying
+- [light-client](./light-client) - Tendermint light client library for verifying
   signed headers, tracking validator set changes, and detecting forks
-- [light-node][tendermint-light-node-docs-link] - Tendermint light client binary
 
-## Installation
+Binaries:
 
-Requires Rust 1.39+
+- [light-node](./light-node) - Tendermint light node to synchronize with a
+  blockchain using the light client 
 
-## Documentation
+## Releases
+
+Release tags can be found on [Github](https://github.com/informalsystems/tendermint-rs/releases).
 
-See documentation on [crates.io](#releases).
+Crates are released on crates.io.
 
 ## Contributing
 
@@ -43,8 +49,8 @@ The Tendermint protocols are specified in English in the
 Any protocol changes or clarifications should be contributed there.
 
 This repo contains the TLA+ specifications and Rust implementations for
-various components of Tendermint. If you're interested in contributing, please
-comment on an issue or open a new one!
+various components of Tendermint. See the [CONTRIBUTING.md][contributing] to start
+contributing.
 
 ## Versioning
 
@@ -102,7 +108,7 @@ limitations under the License.
 [audit-link]: https://github.com/informalsystems/tendermint-rs/actions?query=workflow%3AAudit-Check
 [license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg
 [license-link]: https://github.com/interchainio/tendermint-rs/blob/master/LICENSE
-[rustc-image]: https://img.shields.io/badge/rustc-1.39+-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.44+-blue.svg
 
 [//]: # (general links)
 
@@ -111,4 +117,4 @@ limitations under the License.
 [Tendermint]: https://github.com/tendermint/tendermint
 [tendermint-light-client-docs-link]: https://docs.rs/tendermint-light-client/
 [tendermint-light-node-docs-link]: https://docs.rs/tendermint-light-node/
- 
+[contributing]: ./CONTRIBUTING.md

README.md

@@ -0,0 +1,6 @@
+# Light Client Detection
+
+This is a work in progress. There are two drafts.
+One from the view of a [light node](./detection.md)
+and one from the view of [IBC](./req-ibc-detection.md).
+They are both works in progress and may be consolidated.

docs/spec/lightclient/detection/README.md

@@ -1,17 +1,12 @@
 [![Crate][crate-image]][crate-link]
 [![Docs][docs-image]][docs-link]
-[![Build Status][build-image]][build-link]
-[![Audit Status][audit-image]][audit-link]
-[![Apache 2.0 Licensed][license-image]][license-link]
-![Rust 1.44+][rustc-image]
 
-# Light-Client
-
-Implementation of the [Light Client Verification Protocol][light-client-verification].
+See the [repo root] for build status, license, rust version, etc.
 
-## Requirements
+# Light-Client
 
-Tested with Rust 1.44+, may work on older versions.
+Implementation of the [Light Client Verification][light-client-verification]
+and [Fork Detection][light-client-detection] protocols.
 
 ## Documentation
 
@@ -64,38 +59,17 @@ loop {
 }
 ```
 
-## License
-
-Copyright © 2020 Informal Systems
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use the files in this repository except in compliance with the License.
-You may obtain a copy of the License at
-
-    https://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
 [//]: # (badges)
 
 [crate-image]: https://img.shields.io/crates/v/tendermint-light-client.svg
 [crate-link]: https://crates.io/crates/tendermint-light-client
 [docs-image]: https://docs.rs/tendermint-light-client/badge.svg
 [docs-link]: https://docs.rs/tendermint-light-client/
-[build-image]: https://github.com/informalsystems/tendermint-rs/workflows/Rust/badge.svg
-[build-link]: https://github.com/informalsystems/tendermint-rs/actions?query=workflow%3ARust
-[audit-image]: https://github.com/informalsystems/tendermint-rs/workflows/Audit-Check/badge.svg
-[audit-link]: https://github.com/informalsystems/tendermint-rs/actions?query=workflow%3AAudit-Check
-[license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg
-[license-link]: https://github.com/interchainio/tendermint-rs/blob/master/LICENSE
-[rustc-image]: https://img.shields.io/badge/rustc-1.44+-blue.svg
 
 [//]: # (general links)
 
+[repo root]: https://github.com/informalsystems/tendermint-rs
 [quick start]: https://github.com/tendermint/tendermint/blob/master/docs/introduction/quick-start.md
 [Tendermint]: https://github.com/tendermint/tendermint
 [light-client-verification]: https://github.com/informalsystems/tendermint-rs/blob/master/docs/spec/lightclient/verification/verification.md
+[light-client-detection]: https://github.com/informalsystems/tendermint-rs/tree/master/docs/spec/lightclient/detection

light-client/README.md

@@ -1,3 +1,8 @@
+[![Crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+
+See the [repo root] for build status, license, rust version, etc.
+
 # Light-Node
 
 The [Tendermint] light-node wraps the [light-client] crate into a command-line interface tool. 
@@ -237,7 +242,17 @@ Example output:
 
 </details>
 
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/tendermint-light-node.svg
+[crate-link]: https://crates.io/crates/tendermint-light-node
+[docs-image]: https://docs.rs/tendermint-light-node/badge.svg
+[docs-link]: https://docs.rs/tendermint-light-node/
+
+[//]: # (general links)
+
 
+[repo root]: https://github.com/informalsystems/tendermint-rs
 [quick start]: https://github.com/tendermint/tendermint/blob/master/docs/introduction/quick-start.md
 [Tendermint]: https://github.com/tendermint/tendermint
-[light-client]: https://github.com/informalsystems/tendermint-rs/tree/master/light-client
+[light-client]: https://github.com/informalsystems/tendermint-rs/tree/master/light-client

light-node/README.md

@@ -1,3 +1,8 @@
+[![Crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+
+See the [repo root] for build status, license, rust version, etc.
+
 # tendermint-rpc
 
 A rust implementation of the core types returned by a Tendermint node's RPC 
@@ -6,8 +11,9 @@ These can be used to deserialize JSONRPC responses.
 All networking related features will be feature guarded to keep the dependencies small 
 in cases where only the core types are needed.
 
-Releases of this crate should be compatible to the same [tendermint] version as
-the [tendermint.rs] crate with the same version number.    
+## Documentation
+
+See documentation on [crates.io][docs-link].
 
 ## The `client` Feature
 
@@ -21,6 +27,17 @@ To keep dependencies small when only the core types are needed, it has to be exp
 - RPC endpoints REST interface documentation:
 https://docs.tendermint.com/master/rpc/ 
 
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/tendermint-rpc.svg
+[crate-link]: https://crates.io/crates/tendermint-rpc
+[docs-image]: https://docs.rs/tendermint-rpc/badge.svg
+[docs-link]: https://docs.rs/tendermint-rpc/
+
+[//]: # (general links)
+
+
+[repo root]: https://github.com/informalsystems/tendermint-rs
 [tendermint]: https://github.com/tendermint/tendermint
 [core types]: https://github.com/tendermint/tendermint/blob/8b4a30fada85fccd8f0cb15009344f1cbd8de616/rpc/core/types/responses.go#L1
-[tendermint.rs]: https://crates.io/crates/tendermint
+[tendermint.rs]: https://crates.io/crates/tendermint

rpc/README.md

@@ -0,0 +1,24 @@
+[![Crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+
+See the [repo root] for build status, license, rust version, etc.
+
+# tendermint
+
+Implementation of the [Tendermint] Blockchain Data Structures.
+
+## Documentation
+
+See documentation on [crates.io][docs-link].
+
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/tendermint.svg
+[crate-link]: https://crates.io/crates/tendermint
+[docs-image]: https://docs.rs/tendermint/badge.svg
+[docs-link]: https://docs.rs/tendermint/
+
+[//]: # (general links)
+
+[repo root]: https://github.com/informalsystems/tendermint-rs
+[Tendermint]: https://github.com/tendermint/tendermint