-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
More rust training content #7
Changes from all commits
b11be93
578f06d
7f4fb0d
207b056
8a49b1d
7693500
296f0b2
32311e6
2468e86
1bfb08b
f4afd81
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,2 @@ | ||
*~ | ||
yarn-error.log | ||
target/ |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
index.html |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
TODO organize this | ||
|
||
Every md file has a html relative symlink to index.html: | ||
|
||
`ln -s index.html CONTRIBUTING.html` | ||
|
||
The static website loads the page content from markdown dynamically, | ||
based on the URL of its HTML page. | ||
|
||
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. | ||
|
||
Project 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: | ||
|
||
> <i>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.</i> | ||
|
||
> _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 an html 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 | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,16 +3,14 @@ | |
A training course on practical software construction in Rust. | ||
|
||
The final project in this course is a networked, persistent [key-value store] | ||
with multithreading, asynchronous I/O (via [tokio] and [tower]), a | ||
high-performance network protocol ([GRPC] via [prost] and [tower-grpc]), | ||
backed by a simple [LSM-tree] that the student will write themselves. | ||
with multithreading, asynchronous I/O (via [hyper]). | ||
|
||
Subjects covered include: | ||
|
||
- Structuring and maintaining Rust programs | ||
- Fun and foolproof parallel programming | ||
- Asyncronous programming with [futures] and [tokio] | ||
- High-performance networking with [GRPC] and [prost] | ||
- Asyncronous programming with [futures] | ||
- Networking with [hyper] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hyper focuses on the HTTP protocol. I wonder what kind of service this subject will accomplish? (Plain HTTP 1.0 APIs or HTTP2 steaming APIs) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I wasn't planning to do anything HTTP2 specific, though I assume hyper will negotiate a HTTP2 upgrade if it can. Do you have any suggestions? I'm torn about using HTTP for this, since gRPC is what PingCAP uses. But @siddontang and I discussed that it may be too much to require gRPC for this project. If we don't do gRPC in the initial set of projects, I'm thinking it could be in a subsequent project. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think teaching 'networking with Hyper' is not a good idea since we don't use it at pingCAP (afaik) and it is not an essential library and the domain is still in flux. I think it is OK to use Hyper, just emphasize that we're teaching networking in Rust rather than any particular library (could even just use TCP?) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
- Benchmarking with [criterion] and [critcmp] | ||
- Robust and reliable error handling with [failure] | ||
- Serialization with [serde] | ||
|
@@ -119,7 +117,7 @@ recommended to teach this course. | |
|
||
## Contributing | ||
|
||
TODO | ||
See [CONTRIBUTING.md]. | ||
|
||
## License | ||
|
||
|
@@ -148,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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
/* Styles for non-slide pages */ | ||
|
||
section#content { | ||
margin-top: 5.5rem; /* nav border * 2 + line-height + 2rem */ | ||
} | ||
|
||
section#content { | ||
padding-left: 100px; | ||
padding-right: 100px; | ||
} | ||
|
||
pre { | ||
background-color: #555; | ||
color: white; | ||
padding: 1rem; | ||
} | ||
|
||
body { | ||
margin-bottom: 5rem; | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -37,6 +37,9 @@ in the README. | |
- Ana likes this | ||
- variable shadowing | ||
- DSTs | ||
- configuring clippy / rustfmt | ||
- scripting clippy / rustfmt for CI | ||
- CI setup | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. +1, it is very important for open-source projects, I just fixed a bug today during setting up CI. But which one do we want to target? Maybe we can make a list of CI doc link, let students choose. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Offhand I'd prefer to be opinionated and pick either travis or circle, whichever has the most open source mindshare (or maybe whichever pingcap uses). That way we can be specific about requirements, and have a better chance at automatically verifying they set up CI correctly. It's not a strong opinion though. It's also a chance to talk about the README and other boilerplate files, the various badges and other services Rust projects typically use. |
||
|
||
## Sources | ||
|
||
|
@@ -51,25 +54,22 @@ in the README. | |
|
||
## Subjects to potentially cut | ||
|
||
- Whirlwind rust lesson | ||
- Parallelism section | ||
- Formatting lesson | ||
- Build time lesson | ||
- Collections and iterators | ||
|
||
## Contributor notes | ||
## Grading | ||
|
||
- 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 | ||
- automated text-based cheat detection | ||
- automated grading of test cases | ||
- automated grading of non-unit-test requirements via python script | ||
- how to grade freeform answers? | ||
|
||
## 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Better to explain the reason? I first felt confused until I find out we are loading the md dynamically according to the url.