Starting a new Governance section on docs (#554)

docs/governance/governance.md

@@ -0,0 +1,27 @@
+---
+
+*Decred* (/ˈdi:ˈkred/, /dɪˈkred/, dee-cred) is an open, progressive, and self-funding cryptocurrency with a system of community-based governance integrated into its blockchain. The project mission is to develop technology for the public benefit, with a primary focus on cryptocurrency technology.
+
+Decred's governance is based on the principle of ticket-holder voting. The ultimate decision-making force for the project is the voting of active tickets.
+
+---
+
+Holders of DCR can time-lock their funds in exchange for [tickets](/mining/proof-of-stake.md). Tickets allow one to participate in Decred's governance in three ways, two on-chain and one off-chain.
+
+In each block, five live tickets are selected pseudo-randomly and called to vote on-chain. Tickets are called to vote after an average of around 28 days, once a ticket has voted the DCR which was time-locked to buy it matures (un-locks) after 256 blocks, along with a portion of the block reward.
+
+On-chain voting serves the following purposes:
+
+1. [Agenda voting](getting-started/user-guides/agenda-voting/) to *approve or reject a proposed change to the consensus rules* of the protocol. A proposed change must be approved by 75% of non-abstaining tickets to take effect.
+
+1. Voting to *approve the work of PoW Miners*. In order for a PoW Miner to receive their share of the block reward, at least three of the five tickets called in the subsequent block must approve their block. This gives ticket-holders power over PoW Miners in the case of undesirable behavior by miners (e.g. mining empty blocks), although this power is yet to be exercised on mainnet.
+
+Decred's on-chain governance is supplemented by *Politeia proposal voting*, which doesn't happen directly on-chain but is woven into the Decred blockchain in some ways. 
+
+Politeia proposals concern the direction of the project, they may involve spending the [project subsidy fund](http://explorer.dcrdata.org/address/Dcur2mcGjmENx4DhNqDctW5wJCVyT3Qeqkx) (10% of the block reward goes into this fund to support development of the project) or amending the [Decred Constitution](/getting-started/constitution.md) or other policies.
+
+Politeia proposals are anchored to the Decred blockchain using [dcrtime](https://github.com/decred/dcrtime), making them "censor-proof" - one can prove when one's contributions have been censored.
+
+The [Politeia web platform](https://proposals.decred.org/) is a reddit-style space to facilitate submitting, viewing and discussing proposals.
+
+Politeia proposals are approved/rejected through "snap" voting. When proposals move to a vote, all live tickets at that moment are eligible to vote Yes/No on the proposal while voting remains open (one week period). Ticket-holders vote through their wallet.

docs/governance/politeia.md

@@ -0,0 +1,48 @@
+
+**What is Politeia?**
+
+Politeia, or Pi, is a platform which is being developed to support Decred’s governance. It facilitates the submission, tracking, and discussion of Decred governance proposals by the stakeholder community.
+
+The Politeia web platform (at [proposals.decred.org](https://proposals.decred.org/)) facilitates browsing, discussing and submitting proposals.
+
+**Politeia proposals**
+
+There are two broad types of proposal:
+
+1. Proposals that aim to establish Voter support for a course of action, e.g. direction of software development, adopting or changing some policy.
+2. Proposals that commit to spending project fund DCR, creating a budget that some entity can draw down against as they demonstrate progress towards the proposal's aim.
+
+There is a fee for submitting a proposal (0.1 DCR), to limit the potential for proposal spamming. There is also a fee for registering a Politeia account (0.1 DCR), to limit comment spam and up/down voting sock-puppetry. Fees may be altered if a) they're not a sufficient spam-deterrent, or b) the price of DCR changes considerably.
+
+Reddit-style **up/down voting** is used for **proposal and comment sorting only**. Up/down votes are not anonymous.
+
+Ticket-voting on proposals doesn’t happen directly on Politeia, but from within a Decred wallet.
+
+**Censorship**  
+
+When proposals are submitted, they are checked by Politeia administrators. Proposals that are deemed spam or invalid will be censored.
+
+Politeia is _*censor-proof_,* using ***dcrtime\***. Users cannot be silently censored, they can prove that censorship has occurred. When a proposal/comment is submitted, a censorship token is generated. Content creators can use these tokens to demonstrate that their specific proposal/comment was submitted, in a particular form, at a particular point in time.
+
+To access this censor-proof feature, **Politeia users have cryptographic identities** (pub/priv key pairs) to go with their accounts. When you register for a Politeia account, a key-pair identity will be generated for you, this is stored in your browser by default.  
+
+If you change browser/device you can import your Pi identity key or generate a new one, but for now it is important to *verify your account from the same browser you used to sign up*. The cryptographic Pi identity is only used for demonstrating that your submissions have been censored.
+
+**Submitting and approving proposals**
+
+Politeia's aim is to serve as the decision-making force behind the Decred Decentralized Autonomous Entity (DAE). This is an ambitious aim, Politeia and its accompanying processes are in an experimental stage and thus subject to change.
+
+For now, the process is something like this:
+
+1. Submit proposal.
+2. Proposal reviewed by Politeia admins, spam is censored.
+3. Valid proposals appear publicly on Politeia, open for discussion, but voting does not begin immediately.  	
+4. Ticket-voting interval (~1 week) can be triggered by the proposal owner. Until ticket-voting is triggered, the proposal can be edited by its owner in response to community feedback.
+5. Ticket-voting starts, ticket-holders vote through their wallet (details tbc).
+6. When the ticket-voting period ends, the proposal is formally approved or rejected. Some types of proposal will require a super-majority. Details like supermajorities and quorum required for different kinds of proposal are to be determined. 
+7. When a proposal with a budget and deliverables is approved, work can 	begin. The proposal owner can submit claims against that budget as deliverables are completed.
+8. Payment claims will be handled manually by Decred Holdings Group until such times as this process can be adequately decentralized.
+
+Proposal voting works, initially, as a robust signalling mechanism from the Decred stakeholders to the people who control the project fund wallet. Over time, this will be iterated towards a DAE that decentralizes the functions currently performed by trusted humans. When the DAE is ready, it will control the project fund wallet directly.
+
+For proposals that request funding, an initial set of guidelines and examples has been prepared (see bottom of this page)[https://github.com/decred/politeia/blob/master/politeia.md]. Guidelines for good proposals and policies for censoring proposals will be iterated once Politeia is live.

mkdocs.yml

@@ -39,9 +39,11 @@ pages:
   - "Beginner's Guide": 'getting-started/beginner-guide.md'
   - 'Obtaining DCR': 'getting-started/obtaining-dcr.md'
   - 'Using the Block Explorer': 'getting-started/using-the-block-explorer.md'
-  - 'Mainnet Voting': 'getting-started/user-guides/agenda-voting.md'
-  - 'How To Vote': 'getting-started/user-guides/how-to-vote.md'
-  - 'Using Testnet': 'getting-started/using-testnet.md'
+- Governance:
+  - 'Introduction to Decred governance': 'getting-started/governance.md'
+  - 'Consensus rules voting': 'getting-started/user-guides/agenda-voting.md'
+  - 'How to Vote on consensus rule changes': 'getting-started/user-guides/how-to-vote.md'
+  - 'Politeia proposals and voting': 'getting-started/politeia.md' 
   - 'Decred Constitution': 'getting-started/constitution.md'
 - Wallets:
     - Decrediton (GUI):
@@ -58,7 +60,7 @@ pages:
       - 'dcrd and dcrwallet CLI Arguments': 'getting-started/dcrd-and-dcrwallet-cli-arguments.md'
       - 'dcrctl RPC Commands': 'getting-started/dcrctl-rpc-commands.md'
     - 'Web Wallet': 'getting-started/user-guides/web.md'
-- Proof-of-Stake Mining:
+- Proof-of-Stake Voting:
   - "What is Proof-of-Stake?": 'mining/proof-of-stake.md'
   - "How to Stake": 'mining/how-to-stake.md' 
   - PoS FAQ:
@@ -79,6 +81,7 @@ pages:
   - 'Blocks': 'faq/blocks.md'
   - 'Common Errors and Solutions': 'faq/errors.md'
 - Advanced:
+  - 'Using Testnet': 'getting-started/using-testnet.md'
   - 'Manual CLI Installation': 'advanced/manual-cli-install.md'
   - 'Storing Login Details': 'advanced/storing-login-details.md'
   - 'Block Header Specifications': 'advanced/block-header-specifications.md'