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 de2f9e697..2dbde8e1b 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 e8095b892..e3daae2ce 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 51fd9681b..f7aa8bb76 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 7409ba604..29588ca7a 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 000000000..a5b884e84 --- /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 f21f73460..301c120c6 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 eeeb4655d..000000000 --- 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 6e0c23d23..000000000 --- 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 14063a527..000000000 --- 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 ab526be7a..000000000 --- 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 c9a41307c..000000000 --- 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 d55dd9ae6..000000000 --- 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.