Move the design proposals to a separate book

Fixes #3262

.gitignore

@@ -5,6 +5,9 @@
 /book/html/
 /book/src/img/
 /book/src/tests.ok
+/proposals/html/
+/proposals/src/img/
+/proposals/src/tests.ok
 
 **/*.rs.bk
 .cargo

CONTRIBUTING.md

@@ -92,16 +92,13 @@ understood. Avoid introducing new 3-letter terms, which can be confused with 3-l
 Design Proposals
 ---
 
-Solana's architecture is described by a book generated from markdown files in
-the `book/src/` directory, maintained by an *editor* (currently @garious). To
-add a design proposal, you'll need to at least propose a change the content
-under the [Accepted Design
-Proposals](https://solana-labs.github.io/book-edge/proposals.html) chapter.
-Here's the full process:
+Solana's design proposals are part of a book generated from markdown files in
+the `proposals/src/` directory. To add a design proposal:
 
 1. Propose a design by creating a PR that adds a markdown document to the
-   directory `book/src/` and references it from the [table of
-   contents](book/src/SUMMARY.md). Add any relevant *maintainers* to the PR review.
+   directory `proposals/src/` and references it from the [table of
+   contents](proposals/src/SUMMARY.md). Add any relevant *maintainers* to the PR
+   review.
 2. The PR being merged indicates your proposed change was accepted and that the
    maintainers support your plan of attack.
 3. Submit PRs that implement the proposal. When the implementation reveals the

book/README.md

@@ -1,7 +1,7 @@
 Building the Solana book
 ---
 
-Install the book's dependnecies, build, and test the book:
+Install the book's dependencies, build, and test the book:
 
 ```bash
 $ ./build.sh

book/src/SUMMARY.md

@@ -33,31 +33,3 @@
   - [JSON RPC API](jsonrpc-api.md)
   - [JavaScript API](javascript-api.md)
   - [solana-wallet CLI](wallet.md)
-
-- [Accepted Design Proposals](proposals.md)
-  - [Ledger Replication](ledger-replication-to-implement.md)
-  - [Secure Vote Signing](vote-signing-to-implement.md)
-  - [Staking Rewards](staking-rewards.md)
-  - [Passive Stake Delegation and Rewards](passive-stake-delegation-and-rewards.md)
-  - [Fork Selection](fork-selection.md)
-  - [Reliable Vote Transmission](reliable-vote-transmission.md)
-  - [Persistent Account Storage](persistent-account-storage.md)
-  - [Cluster Economics](ed_overview.md)
-    - [Validation-client Economics](ed_validation_client_economics.md)
-      - [State-validation Protocol-based Rewards](ed_vce_state_validation_protocol_based_rewards.md)
-      - [State-validation Transaction Fees](ed_vce_state_validation_transaction_fees.md)
-      - [Replication-validation Transaction Fees](ed_vce_replication_validation_transaction_fees.md)
-      - [Validation Stake Delegation](ed_vce_validation_stake_delegation.md)
-    - [Replication-client Economics](ed_replication_client_economics.md)
-      - [Storage-replication Rewards](ed_rce_storage_replication_rewards.md)
-      - [Replication-client Reward Auto-delegation](ed_rce_replication_client_reward_auto_delegation.md)
-    - [Economic Sustainability](ed_economic_sustainability.md)
-    - [Attack Vectors](ed_attack_vectors.md)
-	- [Economic Design MVP](ed_mvp.md)
-    - [References](ed_references.md)
-  - [Cluster Test Framework](cluster-test-framework.md)
-  - [Testing Programs](testing-programs.md)
-
-- [Implemented Design Proposals](implemented-proposals.md)
-  - [Leader-to-Leader Transition](leader-leader-transition.md)
-  - [Leader-to-Validator Transition](leader-validator-transition.md)

book/src/proposals.md

@@ -1,7 +0,0 @@
-# Proposed Architectural Changes
-
-The following architectural proposals have been accepted by the Solana team, but
-are not yet fully implemented. The proposals may be implemented as described,
-implemented differently as issues in the designs become evident, or not
-implemented at all. If implemented, the descriptions will be moved from this
-section to earlier chapters in a future version of this book.

ci/test-checks.sh

@@ -15,5 +15,6 @@ _ cargo clippy --all -- --deny=warnings
 _ ci/audit.sh
 _ ci/nits.sh
 _ book/build.sh
+_ proposals/build.sh
 
 echo --- ok

proposals/README.md

@@ -0,0 +1,26 @@
+Building the Solana Design Proposals HTML
+---
+
+Install the book's dependencies, build, and test the book:
+
+```bash
+$ ./build.sh
+```
+
+Run any Rust tests in the markdown:
+
+```bash
+$ make test
+```
+
+Render markdown as HTML:
+
+```bash
+$ make build
+```
+
+Render and view the book:
+
+```bash
+$ make open
+```

proposals/book.toml

@@ -0,0 +1,10 @@
+[book]
+title = "Solana Design Proposals"
+authors = ["The Solana Team"]
+
+[build]
+build-dir = "html"
+create-missing = false
+
+[output.html]
+theme = "../book/theme"

proposals/build.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -e
+
+cd "$(dirname "$0")"
+
+cargo_install_unless() {
+  declare crate=$1
+  shift
+
+  "$@" > /dev/null 2>&1 || \
+    cargo install "$crate"
+}
+
+export PATH=$CARGO_HOME/bin:$PATH
+cargo_install_unless mdbook mdbook --help
+cargo_install_unless svgbob_cli svgbob --help
+
+make -j"$(nproc)"

proposals/makefile

@@ -0,0 +1,33 @@
+BOB_SRCS=$(wildcard art/*.bob)
+MD_SRCS=$(wildcard src/*.md)
+
+SVG_IMGS=$(BOB_SRCS:art/%.bob=src/img/%.svg)
+
+all: html/index.html
+
+test: src/tests.ok
+
+open: all
+	mdbook build --open
+
+watch: $(SVG_IMGS)
+	mdbook watch
+
+src/img/%.svg: art/%.bob
+	@mkdir -p $(@D)
+	svgbob < $< > $@
+
+src/%.md: %.md
+	@mkdir -p $(@D)
+	@cp $< $@
+
+src/tests.ok: $(SVG_IMGS) $(MD_SRCS)
+	mdbook test
+	touch $@
+
+html/index.html: src/tests.ok
+	mdbook build
+
+clean:
+	rm -f $(SVG_IMGS) src/tests.ok
+	rm -rf html

proposals/src/SUMMARY.md

@@ -0,0 +1,29 @@
+# Solana Design Proposals
+
+- [Accepted Design Proposals](proposals.md)
+  - [Ledger Replication](ledger-replication-to-implement.md)
+  - [Secure Vote Signing](vote-signing-to-implement.md)
+  - [Staking Rewards](staking-rewards.md)
+  - [Passive Stake Delegation and Rewards](passive-stake-delegation-and-rewards.md)
+  - [Fork Selection](fork-selection.md)
+  - [Reliable Vote Transmission](reliable-vote-transmission.md)
+  - [Persistent Account Storage](persistent-account-storage.md)
+  - [Cluster Economics](ed_overview.md)
+    - [Validation-client Economics](ed_validation_client_economics.md)
+      - [State-validation Protocol-based Rewards](ed_vce_state_validation_protocol_based_rewards.md)
+      - [State-validation Transaction Fees](ed_vce_state_validation_transaction_fees.md)
+      - [Replication-validation Transaction Fees](ed_vce_replication_validation_transaction_fees.md)
+      - [Validation Stake Delegation](ed_vce_validation_stake_delegation.md)
+    - [Replication-client Economics](ed_replication_client_economics.md)
+      - [Storage-replication Rewards](ed_rce_storage_replication_rewards.md)
+      - [Replication-client Reward Auto-delegation](ed_rce_replication_client_reward_auto_delegation.md)
+    - [Economic Sustainability](ed_economic_sustainability.md)
+    - [Attack Vectors](ed_attack_vectors.md)
+	- [Economic Design MVP](ed_mvp.md)
+    - [References](ed_references.md)
+  - [Cluster Test Framework](cluster-test-framework.md)
+  - [Testing Programs](testing-programs.md)
+
+- [Implemented Design Proposals](implemented-proposals.md)
+  - [Leader-to-Leader Transition](leader-leader-transition.md)
+  - [Leader-to-Validator Transition](leader-validator-transition.md)

proposals/src/proposals.md

@@ -0,0 +1,7 @@
+# Proposed Architectural Changes
+
+The following architectural proposals have been accepted by the Solana team,
+but are not yet fully implemented. The proposals may be implemented as
+described, implemented differently as issues in the designs become evident, or
+not implemented at all. If implemented, the they will be moved from this
+section to the following one in a future version of this book.