Merge branch 'master' into v0.2

Author: gavofyork

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+## `Polkadot` projects is a **OPENISH Open Source Project**
+-----------------------------------------
+
+## What?
+
+Individuals making significant and valuable contributions are given commit-access to a project to contribute as they see fit. A project is more like an open wiki than a standard guarded open source project.
+
+## Rules
+
+There are a few basic ground-rules for contributors (including the maintainer(s) of the project):
+
+1. **No `--force` pushes** or modifying the Git history in any way. If you need to rebase, ensure you do it in your own repo.
+1. **Non-master branches**, prefixed with a short name moniker (e.g. `gav-my-feature`) must be used for ongoing work.
+1. **All modifications** must be made in a **pull-request** to solicit feedback from other contributors.
+1. A pull-request *must not be merged until CI* has finished successfully.
+1. Contributors should adhere to the house coding style, as specified on the wiki.
+
+Merging pull requests once CI is successful:
+
+1. A pull request that does not alter any logic (e.g. comments, dependencies, docs) may be tagged `insubstantial` and merged by its author.
+1. A pull request with no large change to logic that is an urgent fix may be merged after a non-author contributor has reviewed it well.
+1. All other PRs should sit for 48 hours with the `pleasereview` tag in order to garner feedback.
+1. No PR should be merged until all reviews' comments are addressed.
+
+Reviewing pull requests:
+
+When reviewing a pull request, the end-goal is to suggest useful changes to the author. Reviews should finish with approval unless there are issues that would result in:
+
+1. Buggy behaviour.
+1. Undue maintenance burden.
+1. Breaking with house coding style.
+1. Pessimisation (i.e. reduction of speed as measured in the projects benchmarks).
+1. Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on).
+1. Uselessness (i.e. it does not strictly add a feature or fix a known issue).
+
+Reviews may not be used as an effective veto for a PR because:
+
+1. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix.
+1. It does not fit well with some other contributors' longer-term vision for the project.
+
+## Releases
+
+Declaring formal releases remains the prerogative of the project maintainer(s).
+
+## Changes to this arrangement
+
+This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change.
+
+## Heritage
+
+These contributing guidelines are modified from the "OPEN Open Source Project" guidelines for the Level project: https://github.com/Level/community/blob/master/CONTRIBUTING.md
+
+-----------------------------------------

Cargo.lock

@@ -1,139 +1,106 @@
-# Polkadot
+= Polkadot
+:Author: Polkadot developers
+:Revision: 0.2.0
+:toc:
+:sectnums:
 
 Implementation of a https://polkadot.network node in Rust.
 
-## To play
+== To play
 
 If you'd like to play with Polkadot, you'll need to install a client like this
 one. First, get Rust (1.26.1 or later) and the support software if you don't already have it:
 
-```
+[source, shell]
+----
 curl https://sh.rustup.rs -sSf | sh
 sudo apt install make clang pkg-config libssl-dev
-```
+----
 
 Then, install Polkadot PoC-2:
 
-```
+[source, shell]
 cargo install --git https://github.com/paritytech/polkadot.git --branch v0.2 polkadot
-```
 
 You'll now have a `polkadot` binary installed to your `PATH`. You can drop the
 `--branch v0.2` or run `cargo install --git https://github.com/paritytech/polkadot.git polkadot`
 to get the very latest version of Polkadot, but these instructions might not work in that case.
 
-### Krumme Lanke Testnet
+=== Krumme Lanke Testnet
 
 You will connect to the global Krumme Lanke testnet by default. To do this, just use:
 
-```
+[source, shell]
 polkadot
-```
 
 If you want to do anything on it (not that there's much to do), then you'll need
 to get some Krumme Lanke DOTs. Ask in the Polkadot watercooler.
 
-### Development
+=== Development
 
 You can run a simple single-node development "network" on your machine by
 running in a terminal:
 
-```
+[source, shell]
 polkadot --dev
-```
 
 You can muck around by cloning and building the http://github.com/paritytech/polka-ui and http://github.com/paritytech/polkadot-ui or just heading to https://polkadot.js.org/apps.
 
-## Local Two-node Testnet
+== Local Two-node Testnet
 
 If you want to see the multi-node consensus algorithm in action locally, then
 you can create a local testnet. You'll need two terminals open. In one, run:
 
-```
+[source, shell]
 polkadot --chain=local --validator --key Alice -d /tmp/alice
-```
 
 and in the other, run:
 
-```
+[source, shell]
 polkadot --chain=local --validator --key Bob -d /tmp/bob --port 30334 --bootnodes '/ip4/127.0.0.1/tcp/30333/p2p/ALICE_BOOTNODE_ID_HERE'
-```
 
 Ensure you replace `ALICE_BOOTNODE_ID_HERE` with the node ID from the output of
 the first terminal.
 
-## Hacking on Polkadot
+== Hacking on Polkadot
 
 If you'd actually like hack on Polkadot, you can just grab the source code and
 build it. Ensure you have Rust and the support software installed:
 
-```
+[source, shell]
+----
 curl https://sh.rustup.rs -sSf | sh
 rustup update nightly
 rustup target add wasm32-unknown-unknown --toolchain nightly
 rustup update stable
 cargo install --git https://github.com/alexcrichton/wasm-gc
 sudo apt install cmake pkg-config libssl-dev
-```
+----
 
 Then, grab the Polkadot source code:
 
-```
+[source, shell]
+----
 git clone https://github.com/paritytech/polkadot.git
 cd polkadot
-```
+----
 
 Then build the code:
 
-```
+[source, shell]
+----
 ./build.sh  # Builds the WebAssembly binaries
 cargo build # Builds all native code
-```
+----
 
 You can run the tests if you like:
 
-```
+[source, shell]
 cargo test --all
-```
 
 You can start a development chain with:
 
-```
+[source, shell]
 cargo run -- --dev
-```
-
-## Shell completion
-
-The Polkadot cli command supports shell auto-completion. For this to work, you will need to run the completion script matching you build and system.
-
-Assuming you built a release version using `cargo build --release` and use `bash` run the following:
-```
-source target/release/completion-scripts/polkadot.bash
-```
-
-You can find completion scripts for:
-- bash
-- fish
-- zsh
-- elvish
-- powershell
-
-To make this change persistent, you can proceed as follow:
-### First install
-```
-COMPL_DIR=$HOME/.completion
-mkdir -p $COMPL_DIR
-cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/
-echo "source $COMPL_DIR/polkadot.bash" >> $HOME/.bash_profile
-source $HOME/.bash_profile
-```
-
-### Update
-When you build a new version of Polkadot, the following will ensure you auto-completion script matches the current binary:
-```
-COMPL_DIR=$HOME/.completion
-mkdir -p $COMPL_DIR
-cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/
-source $HOME/.bash_profile
-```
 
+include::doc/packages.adoc[]

README.md renamed to README.adoc

@@ -0,0 +1,33 @@
+
+== Cargo Packages
+
+:leveloffset: +2
+
+include::../polkadot/api/README.adoc[]
+
+include::../polkadot/cli/README.adoc[]
+
+include::../polkadot/collator/README.adoc[]
+
+include::../polkadot/consensus/README.adoc[]
+
+include::../polkadot/executor/README.adoc[]
+
+include::../polkadot/network/README.adoc[]
+
+include::../polkadot/parachain/README.adoc[]
+
+include::../polkadot/primitives/README.adoc[]
+
+include::../polkadot/runtime/README.adoc[]
+
+include::../polkadot/service/README.adoc[]
+
+include::../polkadot/src/README.adoc[]
+
+include::../polkadot/statement-table/README.adoc[]
+
+include::../polkadot/transaction-pool/README.adoc[]
+
+:leveloffset: -2
+

doc/packages.adoc

@@ -0,0 +1,5 @@
+
+= Polkadot API
+
+placeholder
+//TODO Write content :)

polkadot/api/README.adoc

@@ -0,0 +1,11 @@
+
+= Polkadot CLI
+
+== Summary
+
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+include::doc/shell-completion.adoc[]

polkadot/cli/README.adoc

@@ -0,0 +1,41 @@
+
+== Shell completion
+
+The Polkadot cli command supports shell auto-completion. For this to work, you will need to run the completion script matching you build and system.
+
+Assuming you built a release version using `cargo build --release` and use `bash` run the following:
+
+[source, shell]
+source target/release/completion-scripts/polkadot.bash
+
+You can find completion scripts for:
+- bash
+- fish
+- zsh
+- elvish
+- powershell
+
+To make this change persistent, you can proceed as follow:
+
+.First install
+
+[source, shell]
+----
+COMPL_DIR=$HOME/.completion
+mkdir -p $COMPL_DIR
+cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/
+echo "source $COMPL_DIR/polkadot.bash" >> $HOME/.bash_profile
+source $HOME/.bash_profile
+----
+
+.Update
+
+When you build a new version of Polkadot, the following will ensure you auto-completion script matches the current binary:
+
+[source, shell]
+----
+COMPL_DIR=$HOME/.completion
+mkdir -p $COMPL_DIR
+cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/
+source $HOME/.bash_profile
+----

polkadot/cli/doc/shell-completion.adoc

@@ -178,3 +178,20 @@ subcommands:
               long: max-heap-pages
               value_name: COUNT
               help: The maximum number of 64KB pages to ever allocate for Wasm execution. Don't alter this unless you know what you're doing.
+  - revert:
+      about: Revert chain to the previous state
+      args:
+          - NUM:
+              index: 1
+              help: Number of blocks to revert. Default is 256.
+          - chain:
+              long: chain
+              value_name: CHAIN_SPEC
+              help: Specify the chain specification.
+              takes_value: true
+          - base-path:
+              long: base-path
+              short: d
+              value_name: PATH
+              help: Specify custom base path.
+              takes_value: true