From 028b9da0da3a7dca6eddf7e191100d3f163317da Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Sat, 23 Mar 2019 13:27:09 -0600 Subject: [PATCH] Revert "Move the design proposals to a separate book" This reverts commit 4ca18d6b9affbc574d1b3d3d230230b057f8fde3. --- .gitignore | 3 -- CONTRIBUTING.md | 13 +++--- book/README.md | 2 +- book/src/SUMMARY.md | 27 +++++++++++++ .../src/cluster-test-framework.md | 0 {proposals => book}/src/ed_attack_vectors.md | 0 .../src/ed_economic_sustainability.md | 0 {proposals => book}/src/ed_mvp.md | 0 {proposals => book}/src/ed_overview.md | 0 ...plication_client_reward_auto_delegation.md | 0 .../src/ed_rce_storage_replication_rewards.md | 0 {proposals => book}/src/ed_references.md | 0 .../src/ed_replication_client_economics.md | 0 .../src/ed_validation_client_economics.md | 0 ...replication_validation_transaction_fees.md | 0 ...state_validation_protocol_based_rewards.md | 0 ...d_vce_state_validation_transaction_fees.md | 0 .../src/ed_vce_validation_stake_delegation.md | 0 {proposals => book}/src/fork-selection.md | 0 {proposals => book}/src/img/porep_reward.png | Bin .../src/img/solana_economic_design.png | Bin .../img/validation_client_interest_rates.png | Bin .../src/implemented-proposals.md | 0 .../src/leader-leader-transition.md | 0 .../src/leader-validator-transition.md | 0 .../src/ledger-replication-to-implement.md | 0 .../passive-stake-delegation-and-rewards.md | 0 .../src/persistent-account-storage.md | 0 book/src/proposals.md | 7 ++++ .../src/reliable-vote-transmission.md | 0 {proposals => book}/src/staking-rewards.md | 0 {proposals => book}/src/testing-programs.md | 0 .../src/vote-signing-to-implement.md | 0 ci/test-checks.sh | 1 - proposals/README.md | 26 ------------ proposals/book.toml | 10 ----- proposals/build.sh | 18 --------- proposals/makefile | 38 ------------------ proposals/src/SUMMARY.md | 32 --------------- proposals/src/proposals.md | 7 ---- 40 files changed, 43 insertions(+), 141 deletions(-) rename {proposals => book}/src/cluster-test-framework.md (100%) rename {proposals => book}/src/ed_attack_vectors.md (100%) rename {proposals => book}/src/ed_economic_sustainability.md (100%) rename {proposals => book}/src/ed_mvp.md (100%) rename {proposals => book}/src/ed_overview.md (100%) rename {proposals => book}/src/ed_rce_replication_client_reward_auto_delegation.md (100%) rename {proposals => book}/src/ed_rce_storage_replication_rewards.md (100%) rename {proposals => book}/src/ed_references.md (100%) rename {proposals => book}/src/ed_replication_client_economics.md (100%) rename {proposals => book}/src/ed_validation_client_economics.md (100%) rename {proposals => book}/src/ed_vce_replication_validation_transaction_fees.md (100%) rename {proposals => book}/src/ed_vce_state_validation_protocol_based_rewards.md (100%) rename {proposals => book}/src/ed_vce_state_validation_transaction_fees.md (100%) rename {proposals => book}/src/ed_vce_validation_stake_delegation.md (100%) rename {proposals => book}/src/fork-selection.md (100%) rename {proposals => book}/src/img/porep_reward.png (100%) rename {proposals => book}/src/img/solana_economic_design.png (100%) rename {proposals => book}/src/img/validation_client_interest_rates.png (100%) rename {proposals => book}/src/implemented-proposals.md (100%) rename {proposals => book}/src/leader-leader-transition.md (100%) rename {proposals => book}/src/leader-validator-transition.md (100%) rename {proposals => book}/src/ledger-replication-to-implement.md (100%) rename {proposals => book}/src/passive-stake-delegation-and-rewards.md (100%) rename {proposals => book}/src/persistent-account-storage.md (100%) create mode 100644 book/src/proposals.md rename {proposals => book}/src/reliable-vote-transmission.md (100%) rename {proposals => book}/src/staking-rewards.md (100%) rename {proposals => book}/src/testing-programs.md (100%) rename {proposals => book}/src/vote-signing-to-implement.md (100%) delete mode 100644 proposals/README.md delete mode 100644 proposals/book.toml delete mode 100755 proposals/build.sh delete mode 100644 proposals/makefile delete mode 100644 proposals/src/SUMMARY.md delete mode 100644 proposals/src/proposals.md diff --git a/.gitignore b/.gitignore index de2f9e697b..2dbde8e1bc 100644 --- a/.gitignore +++ b/.gitignore @@ -5,9 +5,6 @@ /book/html/ /book/src/img/ /book/src/tests.ok -/proposals/html/ -/proposals/src/img/ -/proposals/src/tests.ok **/*.rs.bk .cargo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8095b892b..e3daae2cef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,13 +92,16 @@ understood. Avoid introducing new 3-letter terms, which can be confused with 3-l Design Proposals --- -Solana's design proposals are part of a book generated from markdown files in -the `proposals/src/` directory. To add a design proposal: +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: 1. Propose a design by creating a PR that adds a markdown document to the - directory `proposals/src/` and references it from the [table of - contents](proposals/src/SUMMARY.md). Add any relevant *maintainers* to the PR - review. + directory `book/src/` and references it from the [table of + contents](book/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 diff --git a/book/README.md b/book/README.md index 51fd9681bf..f7aa8bb762 100644 --- a/book/README.md +++ b/book/README.md @@ -1,7 +1,7 @@ Building the Solana book --- -Install the book's dependencies, build, and test the book: +Install the book's dependnecies, build, and test the book: ```bash $ ./build.sh diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 7409ba604c..29588ca7ae 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -34,3 +34,30 @@ - [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) + - [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) + - [Fork Selection](fork-selection.md) diff --git a/proposals/src/cluster-test-framework.md b/book/src/cluster-test-framework.md similarity index 100% rename from proposals/src/cluster-test-framework.md rename to book/src/cluster-test-framework.md diff --git a/proposals/src/ed_attack_vectors.md b/book/src/ed_attack_vectors.md similarity index 100% rename from proposals/src/ed_attack_vectors.md rename to book/src/ed_attack_vectors.md diff --git a/proposals/src/ed_economic_sustainability.md b/book/src/ed_economic_sustainability.md similarity index 100% rename from proposals/src/ed_economic_sustainability.md rename to book/src/ed_economic_sustainability.md diff --git a/proposals/src/ed_mvp.md b/book/src/ed_mvp.md similarity index 100% rename from proposals/src/ed_mvp.md rename to book/src/ed_mvp.md diff --git a/proposals/src/ed_overview.md b/book/src/ed_overview.md similarity index 100% rename from proposals/src/ed_overview.md rename to book/src/ed_overview.md diff --git a/proposals/src/ed_rce_replication_client_reward_auto_delegation.md b/book/src/ed_rce_replication_client_reward_auto_delegation.md similarity index 100% rename from proposals/src/ed_rce_replication_client_reward_auto_delegation.md rename to book/src/ed_rce_replication_client_reward_auto_delegation.md diff --git a/proposals/src/ed_rce_storage_replication_rewards.md b/book/src/ed_rce_storage_replication_rewards.md similarity index 100% rename from proposals/src/ed_rce_storage_replication_rewards.md rename to book/src/ed_rce_storage_replication_rewards.md diff --git a/proposals/src/ed_references.md b/book/src/ed_references.md similarity index 100% rename from proposals/src/ed_references.md rename to book/src/ed_references.md diff --git a/proposals/src/ed_replication_client_economics.md b/book/src/ed_replication_client_economics.md similarity index 100% rename from proposals/src/ed_replication_client_economics.md rename to book/src/ed_replication_client_economics.md diff --git a/proposals/src/ed_validation_client_economics.md b/book/src/ed_validation_client_economics.md similarity index 100% rename from proposals/src/ed_validation_client_economics.md rename to book/src/ed_validation_client_economics.md diff --git a/proposals/src/ed_vce_replication_validation_transaction_fees.md b/book/src/ed_vce_replication_validation_transaction_fees.md similarity index 100% rename from proposals/src/ed_vce_replication_validation_transaction_fees.md rename to book/src/ed_vce_replication_validation_transaction_fees.md diff --git a/proposals/src/ed_vce_state_validation_protocol_based_rewards.md b/book/src/ed_vce_state_validation_protocol_based_rewards.md similarity index 100% rename from proposals/src/ed_vce_state_validation_protocol_based_rewards.md rename to book/src/ed_vce_state_validation_protocol_based_rewards.md diff --git a/proposals/src/ed_vce_state_validation_transaction_fees.md b/book/src/ed_vce_state_validation_transaction_fees.md similarity index 100% rename from proposals/src/ed_vce_state_validation_transaction_fees.md rename to book/src/ed_vce_state_validation_transaction_fees.md diff --git a/proposals/src/ed_vce_validation_stake_delegation.md b/book/src/ed_vce_validation_stake_delegation.md similarity index 100% rename from proposals/src/ed_vce_validation_stake_delegation.md rename to book/src/ed_vce_validation_stake_delegation.md diff --git a/proposals/src/fork-selection.md b/book/src/fork-selection.md similarity index 100% rename from proposals/src/fork-selection.md rename to book/src/fork-selection.md diff --git a/proposals/src/img/porep_reward.png b/book/src/img/porep_reward.png similarity index 100% rename from proposals/src/img/porep_reward.png rename to book/src/img/porep_reward.png diff --git a/proposals/src/img/solana_economic_design.png b/book/src/img/solana_economic_design.png similarity index 100% rename from proposals/src/img/solana_economic_design.png rename to book/src/img/solana_economic_design.png diff --git a/proposals/src/img/validation_client_interest_rates.png b/book/src/img/validation_client_interest_rates.png similarity index 100% rename from proposals/src/img/validation_client_interest_rates.png rename to book/src/img/validation_client_interest_rates.png diff --git a/proposals/src/implemented-proposals.md b/book/src/implemented-proposals.md similarity index 100% rename from proposals/src/implemented-proposals.md rename to book/src/implemented-proposals.md diff --git a/proposals/src/leader-leader-transition.md b/book/src/leader-leader-transition.md similarity index 100% rename from proposals/src/leader-leader-transition.md rename to book/src/leader-leader-transition.md diff --git a/proposals/src/leader-validator-transition.md b/book/src/leader-validator-transition.md similarity index 100% rename from proposals/src/leader-validator-transition.md rename to book/src/leader-validator-transition.md diff --git a/proposals/src/ledger-replication-to-implement.md b/book/src/ledger-replication-to-implement.md similarity index 100% rename from proposals/src/ledger-replication-to-implement.md rename to book/src/ledger-replication-to-implement.md diff --git a/proposals/src/passive-stake-delegation-and-rewards.md b/book/src/passive-stake-delegation-and-rewards.md similarity index 100% rename from proposals/src/passive-stake-delegation-and-rewards.md rename to book/src/passive-stake-delegation-and-rewards.md diff --git a/proposals/src/persistent-account-storage.md b/book/src/persistent-account-storage.md similarity index 100% rename from proposals/src/persistent-account-storage.md rename to book/src/persistent-account-storage.md diff --git a/book/src/proposals.md b/book/src/proposals.md new file mode 100644 index 0000000000..a5b884e84f --- /dev/null +++ b/book/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 descriptions will be moved from this +section to earlier chapters in a future version of this book. diff --git a/proposals/src/reliable-vote-transmission.md b/book/src/reliable-vote-transmission.md similarity index 100% rename from proposals/src/reliable-vote-transmission.md rename to book/src/reliable-vote-transmission.md diff --git a/proposals/src/staking-rewards.md b/book/src/staking-rewards.md similarity index 100% rename from proposals/src/staking-rewards.md rename to book/src/staking-rewards.md diff --git a/proposals/src/testing-programs.md b/book/src/testing-programs.md similarity index 100% rename from proposals/src/testing-programs.md rename to book/src/testing-programs.md diff --git a/proposals/src/vote-signing-to-implement.md b/book/src/vote-signing-to-implement.md similarity index 100% rename from proposals/src/vote-signing-to-implement.md rename to book/src/vote-signing-to-implement.md diff --git a/ci/test-checks.sh b/ci/test-checks.sh index f21f734605..301c120c62 100755 --- a/ci/test-checks.sh +++ b/ci/test-checks.sh @@ -15,6 +15,5 @@ _ cargo +"$rust_stable" clippy --all -- --deny=warnings _ ci/audit.sh _ ci/nits.sh _ book/build.sh -_ proposals/build.sh echo --- ok diff --git a/proposals/README.md b/proposals/README.md deleted file mode 100644 index eeeb4655d1..0000000000 --- a/proposals/README.md +++ /dev/null @@ -1,26 +0,0 @@ -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 -``` diff --git a/proposals/book.toml b/proposals/book.toml deleted file mode 100644 index 6e0c23d233..0000000000 --- a/proposals/book.toml +++ /dev/null @@ -1,10 +0,0 @@ -[book] -title = "Solana Design Proposals" -authors = ["The Solana Team"] - -[build] -build-dir = "html" -create-missing = false - -[output.html] -theme = "../book/theme" diff --git a/proposals/build.sh b/proposals/build.sh deleted file mode 100755 index 14063a5279..0000000000 --- a/proposals/build.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/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)" diff --git a/proposals/makefile b/proposals/makefile deleted file mode 100644 index ab526be7a0..0000000000 --- a/proposals/makefile +++ /dev/null @@ -1,38 +0,0 @@ -BOB_SRCS=$(wildcard art/*.bob) -MSC_SRCS=$(wildcard art/*.msc) -MD_SRCS=$(wildcard src/*.md) - -SVG_IMGS=$(BOB_SRCS:art/%.bob=src/img/%.svg) $(MSC_SRCS:art/%.msc=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/img/%.svg: art/%.msc - @mkdir -p $(@D) - mscgen -T svg -i $< -o $@ - -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 diff --git a/proposals/src/SUMMARY.md b/proposals/src/SUMMARY.md deleted file mode 100644 index c9a41307cf..0000000000 --- a/proposals/src/SUMMARY.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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) - - [Credit-Only Credit-Debit Accounts](credit-only-credit-debit-accounts.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) - - [Cluster Software Installation and Updates](installer.md) - - [Testnet Participation](testnet-participation.md) diff --git a/proposals/src/proposals.md b/proposals/src/proposals.md deleted file mode 100644 index d55dd9ae6f..0000000000 --- a/proposals/src/proposals.md +++ /dev/null @@ -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 they will be moved from this -section to the following one in a future version of this book.