Merge pull request #18 from poanetwork/ag_doc_updates

Updates to Documentation

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+All notable changes to the project will be documented in this file.
+
+## [0.3.0] - 2018-05-29
+### Added
+- --b flag to specify a block integer. This option displays records starting with a block number.
+- Check of contract address to ensure event handling comes from the correct contracts instance
+- Release binaries to allow for program to run without Cargo installed
+- Additional code commenting and error messaging
+
+### Changed
+- Moved counter code to separate module at counter.rs and refactored counter code
+- -v option extended; displays full lists of participating and abstaining voters for each ballot
+
+### Fixed
+- Switched to `VotingKeyChanged` event to track the current validator set and confirm a mining key is finalized rather than `InitializeChange` event, which was not always finalized.
+
+
+## [0.2.1] - 2018-05-24
+
+### Fixed
+- Web3 compilation issue.
+
+## [0.2.0] - 2018-05-21
+### Added
+-  -p flag to allow user to display limited time periods in which ballots are counted
+
+### Changed
+- Display changed to show current validators only. Validators who have been removed are no longer shown.
+
+### Fixed
+- Fixed server filter registration to allow for use with load-balanced servers and compatibility with https://core.poa.network 
+
+
+## [0.1.0] - 2018-05-19
+### Added
+- Initial implementation
+- GPL3 License
+- Enabled Travis CI
+- ABI and contract address files updated from [poa-chain-spec](https://github.com/poanetwork/poa-chain-spec)
+- Use Ethabi Contract
+- Reference to [RP9 specifications](https://github.com/poanetwork/RFC/issues/9)
+- Enabled build scripts
+- Checks for node sychonization / error messages if nodes are not synced
+- Parsing for validator addresses
+- Updated dependencies including Rust and Clippy
+
+
+[0.3.0]: https://github.com/poanetwork/poa-ballot-stats/releases/tag/0.3.0
+[0.2.1]: https://github.com/poanetwork/poa-ballot-stats/releases/tag/0.2.1
+[0.2.0]: https://github.com/poanetwork/poa-ballot-stats/releases/tag/0.2.0
+[0.1.0]: https://github.com/poanetwork/poa-ballot-stats/releases/tag/0.1.0

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# POA Network
+
+![poa_logo](poa-logo.png)
+
+## To Contribute
+1. Fork the repository
+https://github.com/poanetwork/poa-ballot-stats/fork
+2. Create a feature branch
+3. Write tests to cover the work 
+4. Commit changes
+5. Push to the branch
+6. Create a new pull request following the PR protocol below
+
+## Pull Request (PR) Protocol
+
+All pull requests must include: 
+* A clear, readable description of the purpose of the PR
+* A clear, readable description of changes
+* A title that includes (Fix), (Feature), or (Refactor)
+**example:** (Fix) price of 1 token in Wei > 18 decimals
+* A single commit message for one specific fix or feature. A separate PR should be made for each specific change.
+* Any additional concerns or comments (optional)
+
+All accepted and completed PRs are updated in the Wiki documentation.

README.md

@@ -1,42 +1,89 @@
 # POA ballot stats
 
-A command line tool that displays voting statistics for the [POA network](https://poa.network/).
-It and needs to communicate with a fully synchronized node that is connected to the network:
-[POA installation](https://github.com/poanetwork/wiki/wiki/POA-Installation).
-Note that `poa-ballot-stats` needs access to the network's full logs, so the node must run with
-`--pruning=archive --no-warp`. 
-Initial requirements for the tool described in RFC9 "Statistics of ballots." https://github.com/poanetwork/RFC/issues/9
+![logo](poa-logo.png)  [![Build Status](https://travis-ci.org/poanetwork/poa-ballot-stats.svg?branch=master)](https://travis-ci.org/poanetwork/poa-ballot-stats) 
 
-# Usage
+POA ballot stats is a command line tool used to display voting statistics for the [POA network](https://poa.network/). 
 
-## Stable release
+[Validators](https://github.com/poanetwork/wiki/wiki/Role-of-Validator) on the network engage in active governance, managing their roles and creating on-chain consensus. This is achieved through a balloting process. 
 
-Download the archive for your platform from the latest [release](https://github.com/poanetwork/poa-ballot-stats/releases) and unpack it. Run the tool with `./poa-ballot-stats <options>`.
+Ballot tracking provides transparency for POA token holders and promotes validator accountability. The poa-ballot-stats tool displays active validator voting participation ordered by percentage of missed votes. 
 
-You can view the command line options with `-h`, and specify a different endpoint if your node e.g.
-uses a non-standard port. By default, it tries to connect to a local node `http://127.0.0.1:8545`.
+The default display includes:
+* non-participation/associated ballots
+* missed %
+* truncated voting key
+* truncated mining key
+* first name last name
 
-In verbose mode, with `-v`, the list of collected ballot and key change events is displayed, and for each ballot the list of participating and abstaining voters.
+![Screenshot](screenshot.png)
 
-The `-c` option takes a map with the POA contracts' addresses in JSON format. You can find the 
-current maps for the main and test network the `contracts` folder. By default, it uses `core.json`,
-for the main network.
 
-The `-p` option takes a time interval in hours, days, months, etc. E.g. `-p "10 weeks"` will only count participation in ballots that were created within the last 10 weeks. Alternatively, instead of a _time_, you can specify the earliest block _number_ as a decimal integer with the `-b` option.
+## Dependencies
+Prior to downloading poa-ballot-stats, install and activate a fully synchronized node connected to the POA network. See the [POA installation guide](https://github.com/poanetwork/wiki/wiki/POA-Installation) for instructions.
 
-Examples:
+**Note:** poa-ballot-stats must access the full network logs. Use these flags when running a node: `--pruning=archive --no-warp`
+
+**Example:**
+```bash
+$ parity --chain poa-chain-spec/spec.json --reserved-peers poa-chain-spec/bootnodes.txt --pruning=archive --no-warp
+```
+
+## Installation
+
+### Stable Release
+
+Download the archive for your platform from the latest [release](https://github.com/poanetwork/poa-ballot-stats/releases) and unpack. Run the tool with `./poa-ballot-stats <options>`.
+
+#### Options
+
+`-h, --help` view command line options and help information. 
+
+`<url>` specify a different endpoint if your node uses a non-standard port. The default connects to a local node `http://127.0.0.1:8545`.
+
+`-V, --version` prints version information.
+
+`-v, --verbose` display collected ballot and key change events and the list of participating and abstaining voters for each ballot.
+
+`-c, --contracts <contracts>`  append a map file with POA contract addresses in JSON format. The current maps for the main and test network are in the `contracts` folder. Default is the main network `core.json` file.
+
+`-p, --period <period>`  a time interval in hours, days, months, etc. For example, `-p "10 weeks"` only counts participation in ballots created within the last 10 weeks. 
+
+`-b, --block` takes the earliest block _number_ as a decimal option. For example, `-b 524647` counts participation from block number 524647 onward.
+
+
+**Examples:**
 
 ```bash
-$ ./poa-ballot-stats -h
 $ ./poa-ballot-stats
+$ ./poa-ballot-stats -h
 $ ./poa-ballot-stats https://core.poa.network -v -p "10 weeks"
 $ ./poa-ballot-stats -c contracts/sokol.json https://sokol.poa.network -v
 ```
 
-## Latest code
+### Latest code
 
 If you have a recent version of [Rust](https://www.rust-lang.org/), you can clone this repository and use `cargo run --` instead of `./poa-ballot-stats` to compile and run the latest version of the code.
 
-## Screenshot
+## Troubleshooting
 
-![Screenshot](screenshot.png)
+### No Events Found error
+
+1.	Parity must be fully synced to the correct node and running in full mode, not "light" mode. Check Parity UI and/or Task Manager to confirm Parity is synced and actively connected to peers.
+
+2.	`poa-ballot-stats` must run with a file matching the Parity network node. Use the contracts address file (`-c` option) that matches the network connection. Included are files for the main POA network ("core") and the POA test network ("sokol"). The Parity UI will show the current network selection in green. Make sure this is the correct network, and not the Foundation or other Ethereum network. 
+
+![Screenshot](screenshot2.png)
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. See the [project releases](https://github.com/poanetwork/poa-ballot-stats/releases/) and the [changelog](CHANGELOG.md) for historical changes.
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and pull request protocol.
+
+Future implementations may include the number of yes/no votes for each validator and other data points. Proposed requirements and notes on this issue are described in RFC9 [Statistics of ballots](https://github.com/poanetwork/RFC/issues/9).
+
+## License
+
+This project is licensed under the GNU Lesser General Public License [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0). See the [LICENSE](LICENSE) file for details.