Merge pull request #111 from andogro/ag-example-information

Add documentation and screenshot for network simulation

CONTRIBUTING.md

@@ -8,17 +8,21 @@ Thank your for contributing to this project! We welcome collaborators and expect
 4. Run Rustfmt, Clippy, and all tests to ensure CI rules are satisfied. Correct versions and feature flags can be found in the [`.travis.yml`](https://github.com/poanetwork/hbbft/blob/master/.travis.yml) file.
 5. Commit your changes (`git commit -am 'Add some feature'`).
 6. Push to your branch (`git push origin my-new-feature`).
-7. Create a new Pull Request.
+7. Create a new PR (Pull Request).
 
 ### General
 
+* We strive to follow the [Rust API Guidelines](https://rust-lang-nursery.github.io/api-guidelines/about.html) to maintain consistency and compatibility in our code.     
 * Commits should be one logical change that still allows all tests to pass.  We prefer smaller commits if there could be two levels of logic grouping.  The goal is to provide future contributors (including your future self) the reasoning behind your changes and allow them to cherry-pick, patch or port those changes in isolation to other branches or forks.
-* If during your PR you reveal a pre-existing bug:
-  1. Try to isolate the bug and fix it on an independent branch and PR it first.
-  2. Try to fix the bug in a separate commit from other changes:
-     1. Commit the code in the broken state that revealed the bug originally
-     2. Commit the fix for the bug.
-     3. Continue original PR work.
+* If during your PR you reveal a pre-existing bug and know how to fix it:
+  1. If you can isolate the bug, fix it in a separate PR.
+  2. If the fix depends on your other commits, add it in a separate commit to the same PR.  
+
+    In either case, try to write a regression test that fails because of the bug but passes with your fix.
+
+
+### Issues
+Creating and discussing [Issues](https://github.com/poanetwork/hbbft/issues) provides significant value to the project. If you find a bug you can report it in an Issue.     
 
 ### Pull Requests
 All pull requests should include: 

README.md

@@ -64,9 +64,54 @@ $ cargo test --release
 A basic [example](https://github.com/poanetwork/hbbft/blob/master/examples/README.md) is included to run a network simulation.
 
 ```
-$ cargo run --example simulation --release -- -h
+$ cargo run --example simulation --release
 ```
 
+![Screenshot](screenshot.png)
+
+|  Heading    | Definition                       
+| ----------- | -------------------------------------------------------------------------- | 
+| Epoch       |  Epoch number. In each epoch, transactions are processed in a batch by simulated nodes (default is 10 nodes) on a network. The batch is always output in one piece, with all transactions at once.                                                           | 
+| Min Time   | Time in simulated milliseconds until the first correct (i.e. not faulty) node outputs the batch.                                          |  
+| Max Time   | Time in simulated milliseconds until the last correct node outputs the batch.                                                  |  
+| Txs         | Number of transactions processed in the epoch.                                           |  
+| Msgs/Node   | Average number of messages handled by a node. The counter is cumulative and includes the number of messages handled in the current epoch and all previous epochs.                                                               |  
+| Size/Node   | Average message size (in converted bytes) handled by a node. This is cumulative and includes message size for the current epoch and all previous epochs.                                                             |  
+ 
+
+#### Options
+
+Set different parameters to simulate different transaction and network conditions.
+
+|  Flag                  | Description                         | 
+| ---------------------- | -------------------------------- | 
+| `-h, --help`            | Show help options                   | 
+| `--version`             | Show the version of hbbft |  
+| `-n <n>, --nodes <n>`   | The total number of nodes [default: 10]        |  
+| `-f <f>, --faulty <f>`  | The number of faulty nodes [default: 0]|  
+| `-t <txs>, --txs <txs>` | The number of transactions to process [default: 1000]                     |  
+| `-b <b>, --batch <b>`   | The batch size, i.e. txs per epoch [default: 100]                    |  
+|  `-l <lag>, --lag <lag>` | The network lag between sending and receiving [default: 100]                     |  
+|  `--bw <bw>`             | The bandwidth, in kbit/s [default: 2000]                    |  
+|  `--cpu <cpu>`           | The CPU speed, in percent of this machine's [default: 100]                     |  
+|  `--tx-size <size>`      | The size of a transaction, in bytes [default: 10]                     |  
+
+
+**Examples:**
+
+```bash
+# view options
+$ cargo run --example simulation --release -- -h
+
+# simulate a network with 12 nodes, 2 of which are faulty
+$ cargo run --example simulation --release -- -n 12 -f 2
+
+# increase batch size to 500 transactions per epoch
+$ cargo run --example simulation --release -- -b 500
+
+```
+
+
 ## Current TODOs
 
 See [Issues](https://github.com/poanetwork/hbbft/issues) for all tasks.

TODO

@@ -1,4 +0,0 @@
-TODO
-====
-
-See [Issues](https://github.com/poanetwork/hbbft/issues) for current issues in queue.