Integrate the markdown book into the codebase
This implies that the book should describe exactly what is implemented, and will not lead the way and eventually bitrot as the RFCs do.
|
@ -1,6 +1,6 @@
|
||||||
Cargo.lock
|
Cargo.lock
|
||||||
/target/
|
/target/
|
||||||
/doc/book/
|
/book/
|
||||||
|
|
||||||
**/*.rs.bk
|
**/*.rs.bk
|
||||||
.cargo
|
.cargo
|
||||||
|
|
|
@ -55,19 +55,19 @@ Some terms we currently use regularly in the codebase:
|
||||||
Proposing architectural changes
|
Proposing architectural changes
|
||||||
---
|
---
|
||||||
|
|
||||||
Solana's architecture is described by markdown files in the `doc/` directory, currently maintained
|
Solana's architecture is described by a book generated from markdown files in the `src/` directory,
|
||||||
by @garious. To change the architecture, you'll need to at least propose a change with an RFC document,
|
currently maintained by @garious. To change the architecture, you'll need to at least propose a change
|
||||||
and create an issue to track its implementation. Here's the full process:
|
with an RFC document, and create an issue to track its implementation. Here's the full process:
|
||||||
|
|
||||||
1. Propose to a change to the architecture by creating a PR that adds a markdown document called an RFC
|
1. Propose to a change to the architecture by creating a PR that adds a markdown document called an RFC
|
||||||
(standing for "request for comments") to the directory `rfcs/`. Add at least the maintainer of `doc/`
|
(standing for "request for comments") to the directory `rfcs/`. Add at least the maintainer of the
|
||||||
as a reviewer.
|
markdown book as a reviewer.
|
||||||
2. The PR being merged indicates your proposed change was accepted and that the Solana maintainers
|
2. The PR being merged indicates your proposed change was accepted and that the Solana maintainers
|
||||||
support your plan of attack. Next, create an issue to track its implementation and create a PR
|
support your plan of attack. Next, create an issue to track its implementation and create a PR
|
||||||
that updates the RFC with a link to the issue. This link allows anyone to quickly check the
|
that updates the RFC with a link to the issue. This link allows anyone to quickly check the
|
||||||
implementation status of any RFC.
|
implementation status of any RFC.
|
||||||
3. Submit PRs that implement the RFC. Be sure to reference the issue created above in your PR description.
|
3. Submit PRs that implement the RFC. Be sure to reference the issue created above in your PR description.
|
||||||
Feel free to update the RFC as the implementation reveals the need for tweaks to the architecture,
|
Feel free to update the RFC as the implementation reveals the need for tweaks to the architecture,
|
||||||
but if you do, be sure to add the maintainer of `doc/` as a reviewer to your PR.
|
but if you do, be sure to add the maintainer of the markdown book as a reviewer to your PR.
|
||||||
4. Once the implementation is complete, close the issue. Depending on the scope of the RFC, the maintainer
|
4. Once the implementation is complete, close the issue. Depending on the scope of the RFC, the maintainer
|
||||||
of `doc/` may then create a separate ticket to integrate the RFC into `doc/`.
|
of markdown book may then create a separate ticket to integrate the RFC into the book.
|
||||||
|
|
29
README.md
|
@ -295,6 +295,34 @@ $ git clone https://github.com/solana-labs/solana.git
|
||||||
$ cd solana
|
$ cd solana
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Building the Solana book
|
||||||
|
---
|
||||||
|
|
||||||
|
Install mdbook:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo install mdbook
|
||||||
|
```
|
||||||
|
|
||||||
|
Run any Rust tests in the markdown:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mdbook test
|
||||||
|
```
|
||||||
|
|
||||||
|
Render markdown as HTML:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mdbook build
|
||||||
|
```
|
||||||
|
|
||||||
|
Render and view the book:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mdbook build --open
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
Testing
|
Testing
|
||||||
---
|
---
|
||||||
|
|
||||||
|
@ -443,3 +471,4 @@ better way to solve the same problem, a Pull Request with your solution would mo
|
||||||
welcome! Likewise, if rewriting a test can better communicate what code it's protecting, please
|
welcome! Likewise, if rewriting a test can better communicate what code it's protecting, please
|
||||||
send us that patch!
|
send us that patch!
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -48,10 +48,8 @@ done
|
||||||
# Build the HTML
|
# Build the HTML
|
||||||
export PATH=$CARGO_HOME/bin:$PATH
|
export PATH=$CARGO_HOME/bin:$PATH
|
||||||
maybe_install mdbook
|
maybe_install mdbook
|
||||||
_ cd doc
|
|
||||||
_ mdbook test
|
_ mdbook test
|
||||||
_ mdbook build
|
_ mdbook build
|
||||||
_ cd -
|
|
||||||
|
|
||||||
echo --- ci/localnet-sanity.sh
|
echo --- ci/localnet-sanity.sh
|
||||||
(
|
(
|
||||||
|
|
|
@ -1,25 +0,0 @@
|
||||||
## Building the Solana book
|
|
||||||
|
|
||||||
Install mdbook:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo install mdbook
|
|
||||||
```
|
|
||||||
|
|
||||||
Run any Rust tests in the markdown:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mdbook test
|
|
||||||
```
|
|
||||||
|
|
||||||
Render markdown as HTML:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mdbook build
|
|
||||||
```
|
|
||||||
|
|
||||||
Render and view the book:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mdbook build --open
|
|
||||||
```
|
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 4.8 KiB After Width: | Height: | Size: 4.8 KiB |
Before Width: | Height: | Size: 4.5 KiB After Width: | Height: | Size: 4.5 KiB |
Before Width: | Height: | Size: 7.9 KiB After Width: | Height: | Size: 7.9 KiB |
Before Width: | Height: | Size: 7.3 KiB After Width: | Height: | Size: 7.3 KiB |