migrate to v2 tutorial

Signed-off-by: Alex Chi Z <[email protected]>
skyzh · Jan 19, 2024 · 75d85f4 · 75d85f4
1 parent 6f262d6
commit 75d85f4
Show file tree

Hide file tree

Showing 73 changed files with 2,148 additions and 190 deletions.
diff --git a/mini-lsm-book-wip/.gitignore b/mini-lsm-book-wip/.gitignore
diff --git a/mini-lsm-book-wip/book.toml b/mini-lsm-book-wip/book.toml
diff --git a/mini-lsm-book-wip/src/00-get-started.md b/mini-lsm-book-wip/src/00-get-started.md
diff --git a/mini-lsm-book-wip/src/00-overview.md b/mini-lsm-book-wip/src/00-overview.md
diff --git a/mini-lsm-book-wip/src/00-v1.md b/mini-lsm-book-wip/src/00-v1.md
diff --git a/mini-lsm-book-wip/src/01-block.md b/mini-lsm-book-wip/src/01-block.md
diff --git a/mini-lsm-book-wip/src/02-sst.md b/mini-lsm-book-wip/src/02-sst.md
diff --git a/mini-lsm-book-wip/src/03-memtable.md b/mini-lsm-book-wip/src/03-memtable.md
diff --git a/mini-lsm-book-wip/src/04-engine.md b/mini-lsm-book-wip/src/04-engine.md
diff --git a/mini-lsm-book-wip/src/05-compaction.md b/mini-lsm-book-wip/src/05-compaction.md
diff --git a/mini-lsm-book-wip/src/06-recovery.md b/mini-lsm-book-wip/src/06-recovery.md
diff --git a/mini-lsm-book-wip/src/07-bloom-filter.md b/mini-lsm-book-wip/src/07-bloom-filter.md
diff --git a/mini-lsm-book-wip/src/08-key-compression.md b/mini-lsm-book-wip/src/08-key-compression.md
diff --git a/mini-lsm-book-wip/src/09-whats-next.md b/mini-lsm-book-wip/src/09-whats-next.md
diff --git a/mini-lsm-book-wip/src/SUMMARY.md b/mini-lsm-book-wip/src/SUMMARY.md
diff --git a/mini-lsm-book-wip/src/week1-01-memtable.md b/mini-lsm-book-wip/src/week1-01-memtable.md
diff --git a/mini-lsm-book-wip/src/week1-02-block.md b/mini-lsm-book-wip/src/week1-02-block.md
diff --git a/mini-lsm-book-wip/src/week1-03-sst.md b/mini-lsm-book-wip/src/week1-03-sst.md
diff --git a/mini-lsm-book-wip/src/week1-04-merge-iterator.md b/mini-lsm-book-wip/src/week1-04-merge-iterator.md
diff --git a/mini-lsm-book-wip/src/week1-05-read-path.md b/mini-lsm-book-wip/src/week1-05-read-path.md
diff --git a/mini-lsm-book-wip/src/week1-06-write-path.md b/mini-lsm-book-wip/src/week1-06-write-path.md
diff --git a/mini-lsm-book-wip/src/week1-overview.md b/mini-lsm-book-wip/src/week1-overview.md
diff --git a/mini-lsm-book-wip/src/week2-01-compaction.md b/mini-lsm-book-wip/src/week2-01-compaction.md
diff --git a/mini-lsm-book-wip/src/week2-02-simple.md b/mini-lsm-book-wip/src/week2-02-simple.md
diff --git a/mini-lsm-book-wip/src/week2-03-tiered.md b/mini-lsm-book-wip/src/week2-03-tiered.md
diff --git a/mini-lsm-book-wip/src/week2-04-leveled.md b/mini-lsm-book-wip/src/week2-04-leveled.md
diff --git a/mini-lsm-book-wip/src/week2-05-manifest.md b/mini-lsm-book-wip/src/week2-05-manifest.md
diff --git a/mini-lsm-book-wip/src/week2-06-wal.md b/mini-lsm-book-wip/src/week2-06-wal.md
diff --git a/mini-lsm-book-wip/src/week2-overview.md b/mini-lsm-book-wip/src/week2-overview.md
diff --git a/mini-lsm-book/book.toml b/mini-lsm-book/book.toml
@@ -1,5 +1,5 @@
 [book]
-authors = ["Alex Chi"]
+authors = ["Alex Chi Z"]
 language = "en"
 multilingual = false
 src = "src"
@@ -8,3 +8,7 @@ title = "LSM in a Week"
 [preprocessor.toc]
 command = "mdbook-toc"
 renderer = ["html"]
+
+[output.html]
+additional-css = ["custom.css"]
+git-repository-url = "https://github.com/skyzh/mini-lsm"
diff --git a/mini-lsm-book/custom.css b/mini-lsm-book/custom.css
@@ -0,0 +1,5 @@
+.content img {
+    margin-left: auto;
+    margin-right: auto;
+    display: block;
+}
diff --git a/mini-lsm-book/src/00-overview.md b/mini-lsm-book/src/00-overview.md
@@ -67,7 +67,7 @@ systems.
 
 ## Write Flow
 
-![Write Flow](figures/lsm-tutorial/00-lsm-write-flow.svg)
+![Write Flow](lsm-tutorial/00-lsm-write-flow.svg)
 
 The write flow of LSM contains 4 steps:
 
@@ -80,38 +80,13 @@ The write flow of LSM contains 4 steps:
 
 ## Read Flow
 
-![Read Flow](figures/lsm-tutorial/00-lsm-read-flow.svg)
+![Read Flow](lsm-tutorial/00-lsm-read-flow.svg)
 
 When we want to read a key,
 
 1. We will first probe all the memtables from latest to oldest.
 2. If the key is not found, we will then search the entire LSM tree containing SSTs to find the data.
 
-## Tutorial Overview
-
-![Tutorial Overview](figures/lsm-tutorial/00-lsm-tutorial-overview.svg)
-
-In this tutorial, we will build the LSM tree structure in 7 days:
-
-* Day 1: Block encoding. SSTs are composed of multiple data blocks. We will implement the block encoding.
-* Day 2: SST encoding.
-* Day 3: MemTable and Merge Iterators.
-* Day 4: Block cache and Engine. To reduce disk I/O and maximize performance, we will use moka-rs to build a block cache
-  for the LSM tree. In this day we will get a functional (but not persistent) key-value engine with `get`, `put`, `scan`,
-  `delete` API.
-* Day 5: Compaction. Now it's time to maintain a leveled structure for SSTs.
-* Day 6: Recovery. We will implement WAL and manifest so that the engine can recover after restart.
-* Day 7: Bloom filter and key compression. They are widely-used optimizations in LSM tree structures.
-
-## Development Guide
-
-We provide you starter code (see `mini-lsm-starter` crate), where we simply replace all function body with
-`unimplemented!()`. You can start your project based on this starter code. We provide test cases, but they are very
-simple. We recommend you to think carefully about your implementation and write test cases by yourself.
-
-* You can use `cargo x scheck` to run all test cases and do style check in your codebase.
-* You can use `cargo x copy-test dayX` to copy test cases to the starter code.
-
 ## Community
 
 You may join skyzh's Discord server and study with the mini-lsm community.
@@ -138,3 +113,45 @@ vectorized expression framework if you are also interested in that topic.
 [tweet]: https://twitter.com/andy_pavlo/status/1598137241016360961
 [type-exercise]: https://github.com/skyzh/type-exercise-in-rust
 [bustub]: https://github.com/cmu-db/bustub
+
+<!--
+## Structure
+
+chapters + snacks, clear goal
+
+implement, think, try by yourself
+
+required tasks, check your understanding questions, bonus tasks
+
+## Testing
+
+exploring and understanding is more important than passing all the test cases
+
+testing basic requirements, not the internal structure or something
+
+## Solution
+
+### Checkpoints
+
+the final version, but many things can be simplified, read the docs
+
+comments / tests / not up-to-date with the starter code
+
+### How to use the solutions
+
+## Feedbacks
+
+join the Discord server, your feedback is important, thank GitHub users
+
+## License
+
+### Free forever?
+
+### Video lectures + Review Service + Office Hour?
+
+should have a separate preface (before you start) chapter? and what's new with v2?
+
+## Target audience?
+
+## What will you get after taking this course...
+-->
diff --git a/mini-lsm-book/src/00-v1.md b/mini-lsm-book/src/00-v1.md
@@ -0,0 +1,28 @@
+# Mini-LSM v1
+
+This is a legacy version of the Mini-LSM tutorial and we will not maintain it anymore. We are working on a new version of the tutorial. We keep the legacy version in this book so that the search engine can keep the pages in the index and users can follow the links to the new version of the tutorial.
+
+## V1 Tutorial Overview
+
+![Tutorial Overview](legacy-lsm-tutorial/00-lsm-tutorial-overview.svg)
+
+In this tutorial, we will build the LSM tree structure in 7 days:
+
+* Day 1: Block encoding. SSTs are composed of multiple data blocks. We will implement the block encoding.
+* Day 2: SST encoding.
+* Day 3: MemTable and Merge Iterators.
+* Day 4: Block cache and Engine. To reduce disk I/O and maximize performance, we will use moka-rs to build a block cache
+  for the LSM tree. In this day we will get a functional (but not persistent) key-value engine with `get`, `put`, `scan`,
+  `delete` API.
+* Day 5: Compaction. Now it's time to maintain a leveled structure for SSTs.
+* Day 6: Recovery. We will implement WAL and manifest so that the engine can recover after restart.
+* Day 7: Bloom filter and key compression. They are widely-used optimizations in LSM tree structures.
+
+## Development Guide
+
+We provide you starter code (see `mini-lsm-starter` crate), where we simply replace all function body with
+`unimplemented!()`. You can start your project based on this starter code. We provide test cases, but they are very
+simple. We recommend you to think carefully about your implementation and write test cases by yourself.
+
+* You can use `cargo x scheck` to run all test cases and do style check in your codebase.
+* You can use `cargo x copy-test dayX` to copy test cases to the starter code.
diff --git a/mini-lsm-book/src/01-block.md b/mini-lsm-book/src/01-block.md
@@ -1,5 +1,11 @@
 # Block Builder and Block Iterator
 
+<div class="warning">
+
+This is a legacy version of the Mini-LSM tutorial and we will not maintain it anymore. We are working on a new version of this tutorial and this chapter is now part of [Mini-LSM Week 1 Day 2: Blocks](./week1-02-block.md).
+
+</div>
+
 <!-- toc -->
 
 In this part, you will need to modify:
@@ -23,9 +29,9 @@ The block contains two parts: data and offsets.
 
 ```
 ---------------------------------------------------------------------
-|          data         |          offsets          |      meta     |
-|-----------------------|---------------------------|---------------|
-|entry|entry|entry|entry|offset|offset|offset|offset|num_of_elements|
+| data  | offsets | meta  |
+| ----- | ------- | ----- |
+| entry | entry   | entry | entry | offset | offset | offset | offset | num_of_elements |
 ---------------------------------------------------------------------
 ```
 

diff --git a/mini-lsm-book/src/02-sst.md b/mini-lsm-book/src/02-sst.md
@@ -1,5 +1,11 @@
 # SST Builder and SST Iterator
 
+<div class="warning">
+
+This is a legacy version of the Mini-LSM tutorial and we will not maintain it anymore. We are working on a new version of this tutorial and this chapter is now part of [Mini-LSM Week 1 Day 3: Sorted String Table (SST)](./week1-03-sst.md).
+
+</div>
+
 <!-- toc -->
 
 In this part, you will need to modify:

diff --git a/mini-lsm-book/src/03-memtable.md b/mini-lsm-book/src/03-memtable.md
@@ -1,5 +1,11 @@
 # Mem Table and Merge Iterators
 
+<div class="warning">
+
+This is a legacy version of the Mini-LSM tutorial and we will not maintain it anymore. We are working on a new version of this tutorial and this chapter is now part of [Mini-LSM Week 1 Day 1: Memtable](./week1-01-memtable.md) and [Mini-LSM Week 1 Day 4: Merge Iterator](./week1-04-merge-iterator.md)
+
+</div>
+
 <!-- toc -->
 
 In this part, you will need to modify:

diff --git a/mini-lsm-book/src/04-engine.md b/mini-lsm-book/src/04-engine.md
@@ -1,5 +1,10 @@
 # Storage Engine and Block Cache
 
+<div class="warning">
+
+This is a legacy version of the Mini-LSM tutorial and we will not maintain it anymore. We are working on a new version of this tutorial and this chapter is now part of [Mini-LSM Week 1 Day 5: Read Path](./week1-05-read-path.md) and [Mini-LSM Week 1 Day 6: Write Path](./week1-06-write-path.md)
+
+</div>
 
 <!-- toc -->