Fill out project 1, etc.

rust/CONTRIBUTING.html

@@ -0,0 +1 @@
+index.html

rust/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+TODO organize this
+
+Every md file has a html relative symlink to index.html:
+
+`ln -s index.html CONTRIBUTING.html`
+
+Project text doesn't link directly to documentation resources containing
+solutions - students should learn where to get the answers from the
+pre-requisites and lessons.
+
+Proect text may include inline links to pages that offer explanatios of terms
+and concepts.
+
+Keep the project summary (the **Task**, **Goals**, etc. text) synced between
+plan.md and the project description.
+
+Common sections of project descriptions:
+
+- The project summary (directly after h1)
+- "Introduction"
+- "Project spec"
+
+Headers do not capitalize every word; words after a colon
+are capitalized:
+
+> ## Project spec
+
+> ## Lesson: Tools and good bones
+
+In projects, be clear on when the student should start hacking, and what they
+should be hacking, by writing an imperative statement. Format that command in
+italics:
+
+> _Use [crates.io](https://crates.io) to find the documentation
+for the `clap` crate, and implement the command line interface
+such that the `cli_*` test cases pass._
+
+> _Try it now._
+
+## Developing a new section
+
+Each section provides a similar project to previous sections, while expanding
+the scope and building off of learnings from previous sections. Each project
+lends itself to being extended by the next section's project.
+
+New sections are developed in pairs, to benefit from the feedback.
+
+Approximate workflow:
+
+- Author 1 and 2 collaborate on an outline for the new section, adding it to
+  plan.md, following the format of existing sections. This includes supporting lessons
+  and readings. Submit PR.
+
+- Author 1 writes the entire project description; optionally with test cases if
+  that makes the writing easier. Add new background readings or otherwise modify
+  the section plan as needed. Submit PR. Author 2 reviews.
+
+- Author 2 writes the remaining test cases and an example solution project. Add
+  new background readings or otherwise modify the section plan as needed. Submit
+  PR. Author 1 reviews.
+
+- Author 2 makes changes to the project text for clarification, improvement,
+  scope expansion, etc. Add new background readings or otherwise modify the
+  section plan as needed. Submit PR. Author 1 reviews.
+
+##
+
+When writing a project, look for steps where the design could be specified differently,
+where there are multiple solutions, where there is deeper understanding to be gained,
+and ask questions formulated to get the reader to think more deeply.
+
+Projects should be written to take between 2 - 4 hours to implement.
+
+When writing a project, look for optional "extension" steps that teach
+additional practical subjects, but which either aren't necessary to complete the
+project or require more time and skill to implement. Extenion steps go at the
+end of a project.
+
+## Contributor notes
+
+- each md file needs a relative symlink to index.html
+- lessons need a .slides.html symlink
+- links are generally to markdown files, not html files
+  - exception: links to slides from plan go to the hosted website
+  - all links rewritten when browsed locally
+- in markdown, write links as relative to current directory
+- keep "task", "goals", etc in project intros in sync between "plan.md" and
+  project pages
+

rust/README.md

@@ -117,7 +117,7 @@ recommended to teach this course.
 
 ## Contributing
 
-TODO
+See [CONTRIBUTING.md].
 
 ## License
 
@@ -146,4 +146,5 @@ TODO
 [Distributed Systems in Rust]: todo
 [The Rust Book]: https://doc.rust-lang.org/book/
 [plan]: plan.md
-[serde]: todo
+[serde]: todo
+[CONTRIBUTING.md]: CONTRIBUTING.md

rust/css/text.css

@@ -14,3 +14,7 @@ pre {
 	color: white;
 	padding: 1rem;
 }
+
+body {
+	margin-bottom: 5rem;
+}

rust/notes.md

@@ -37,6 +37,9 @@ in the README.
   - Ana likes this
 - variable shadowing
 - DSTs
+- configuring clippy / rustfmt
+- scripting clippy / rustfmt for CI
+- CI setup
 
 ## Sources
 
@@ -57,21 +60,10 @@ in the README.
 - Build time lesson
 - Collections and iterators
 
-## Contributor notes
-
-- each md file needs a relative symlink to index.html
-- lessons need a .slides.html symlink
-- links are generally to markdown files, not html files
-  - exception: links to slides from plan go to the hosted website
-  - all links rewritten when browsed locally
-- in markdown, write links as relative to current directory
-- keep "task", "goals", etc in project intros in sync between "plan.md" and
-  project pages
-
 ## TODO
 
 - do survey of other sources' subject progression
 - lessons and labs pose questions
 - have a chinese native identify and remove 'hard' words and phrases
 - mention somewhere that we're using rust 2018 only, how to verify
-- change slides.html URLS to link to the hosted file
+- change slides.html URLS to link to the hosted file

rust/plan.md

@@ -25,11 +25,24 @@ A suggested workflow:
 - Follow each project according to their own instructions, writing Rust programs
   that pass the projects' accompanying tests.
 
+As you work through the course content, _please_ be on the lookout for things
+you would improve about the course, and either [submit issues][si] explaining,
+or [submit pull requests][spr] with improvements. _Each accepted pull request
+counts toward extra credit during final evaluation_. Pull requests to any other
+project used during this course count as well. This is an opportunity to gain
+experience contributing to an open-source Rust project. Make this a better
+course for the next to take it than it was for you. That is how open source
+projects evolve.
+
+[si]: https://github.com/pingcap/talent-plan/issues/new
+[spr]: https://github.com/pingcap/talent-plan/compare
+
 
 
 
 ## Section 1 (Setup)
 
+
 ### [Project: Tools and good bones][p-tools]
 
 **Task**: Create an in-memory key/value store that passes simple tests and responds
@@ -47,34 +60,31 @@ to command-line arguments.
 
 **Extensions**: `structopt`, `log` / `slog`,
 
-### [Lesson: Whirlwind Rust][t-whirlwind] ([slides][s-whirlwind])
-
-**Readings**:
-
-- [The Book - Getting Started](https://doc.rust-lang.org/book/ch01-00-getting-started.html)
-- [The Book - Programming a Guessing Game](https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html)
-- [The Book - Common Programming Concepts](https://doc.rust-lang.org/book/ch03-00-common-programming-concepts.html)
-
-**Topics**: Rust and cargo, ownership & borrowing / aliasing & mutability in
-brief, resources
 
 ### [Lesson: Data structures in Rust][t-data] ([slides][s-data])
 
 **Topics**: when to use which struct types, impls, ctor patterns, dtors, reprs,
 padding demo, packed structs, size and alignment in depth, enum
 implementation and optimizations,
 
+
 ### [Lesson: Crates and crates.io][t-crates] ([slides][s-crates])
 
 **Topics**: importing crates, features, debugging and fixing dependencies,
 std vs crate philosophy and history, finding crates
 
+
 ### [Lesson: Rust tooling][t-tools] ([slides][s-tools])
 
+**Readings**:
+  - [`clippy` README](https://github.com/rust-lang/rust-clippy/blob/master/README.md)
+  - [`rustfmt` README](https://github.com/rust-lang/rustfmt/blob/master/README.md)
+
 **Topics**: `#[test]`, how does test work?, what does `cargo run` actually do?,
 clippy, rustfmt, controlling clippy and rustfmt, links to other useful tools,
 cargo / rustc wrapping pattern in depth (ex rustup, `RUSTC_WRAPPER`)
 
+
 ### [Lesson: Formatting, println et. al, log, and slog][t-fmt] ([slides][s-fmt])
 
 **Readings**:
@@ -90,6 +100,7 @@ strings
 
 ## Section 2 (File I/O)
 
+
 ### [Project: File I/O][p-fs]
 
 **Task**: Create a persistent key/value store that can be accessed from the
@@ -126,6 +137,7 @@ unwinding
 
 ## Section 3 (Networking)
 
+
 ### [Project: Networking][p-net]
 
 **Task**: Create a single-threaded, persistent key/value store server and client
@@ -135,22 +147,26 @@ with synchronous networking over the HTTP protocol.
 
 - Use hyper for synchronous networking
 
+
 ### [Lesson: Basic network APIs][t-net] ([slides][s-net])
 
 **Topics**: `std` networking, TCP vs UDP, `reqwest`, blocking HTTP serving w/ Iron
 
+
 ### [Lesson: Build-time Rust][t-build] ([slides][s-build])
 
 **Topics**: build scripts, protobuf compilation example, getting rustc version
 and other useful info, in-depth examples of crates that rely on build scripts
 
+
 ### [Lesson: GPRC and prost][t-grpc] ([slides][s-grpc])
 
 
 
 
 ## Section 4 (Parallelism)
 
+
 ### [Project: Parallelism][p-par]
 
 **Task**: Create a multi-threaded, persistent key/value store server and client
@@ -162,6 +178,7 @@ with synchronous networking via HTTP.
 - Use crossbeam channels
 - Benchmark single-threaded vs multi-threaded
 
+
 ### [Lesson: The big problem — aliasing and mutability][t-alias] ([slides][s-alias])
 
 **Readings**:
@@ -174,6 +191,7 @@ with synchronous networking via HTTP.
 / Sync, uniq / shared vs immutable / mutable, `Rc` and `Arc`, interior
 mutability in depth,
 
+
 ### [Lesson: Ownership and borrowing in practice][t-own] ([slides][s-own])
 
 **Readings**:
@@ -184,10 +202,12 @@ mutability in depth,
 **Topics**: when to use pass-by-value, the performance impact of moves,
 reference-bearing structs
 
+
 ### [Lesson: Parallel Rust][t-par] ([slides][s-par])
 
 **Topics**: sharing vs message passing, thread pools
 
+
 ### [Lesson: Benchmarking, profiling, and debugging][t-prof] ([slides][s-prof])
 
 **Topics**: println debugging, RUST_BACKTRACE, perf, gdb and Rust, std bench vs
@@ -199,6 +219,7 @@ tools
 
 ## Section 5 (Async)
 
+
 ### [Project: Async I/O][p-async]
 
 **Task**: Create a multi-threaded, persistent key/value store server and client
@@ -213,6 +234,7 @@ with asynchronous networking via HTTP.
 
 **Extensions**: crash recovery, async/await
 
+
 ### [Lesson: Basic futures][t-fut] ([slides][s-fut])
 
 **Readings**:
@@ -221,6 +243,7 @@ with asynchronous networking via HTTP.
 
 **Topics**: what are futures?, how to think in futures, futures patterns, mio
 
+
 ### [Lesson: `async` / `await`][t-async-await] ([slides][s-async-await])
 
 **Topics**: futures vs async/await, how does async / await work,
@@ -229,12 +252,17 @@ async borrowing, Pin
 
 
 
+<!--
+
 ## TODOs
 
 - reduce scope
 - fmt subject isn't _necessary_ but is a deep-dive topic
 - need to have a "how to get help" section somewhere
 
+-->
+
+
 
 
 <!-- lesson and project links -->

rust/projects/tools/Cargo.toml

@@ -1,7 +1,8 @@
 [package]
-name = "project_1"
+name = "kvs"
 version = "0.1.0"
 authors = ["Brian Anderson <andersrb@gmail.com>"]
+description = "A key-value store"
 edition = "2018"
 
 [dependencies]