Starting a Real Project

Choosing a Project

In Phase 4, the goal is to complete at least one real project. Here are five guides with different difficulty levels and focus areas:

| Project | One-liner | Key Concepts | Difficulty | | ------------ | ---------------------------------- | -------------------------------- | ---------- | | todo | CLI task manager with JSON storage | serde, clap, file I/O | ** | | minigrep | Search for text in files | File I/O, iterators, env vars | ** | | unitconv | Unit conversion CLI | Traits, generics, testing | ** | | mdhtml | Simple Markdown to HTML converter | Enums (AST), string processing | *** | | minichat | TCP chat server/client | std::net, threads, concurrency | **** |

Tip: Start with todo or minigrep to warm up. Once you feel confident, try unitconv or mdhtml. If you want to explore networking and concurrency, go for minichat.

Kickoff Checklist

1. Define the problem — Write one paragraph answering "Who uses this? In what situation?"
2. MVP features — Pick 3-5 essential features and list them as backlog cards.
3. Input/output examples — For a CLI, write sample commands. For a server, sketch the protocol.
4. Success criteria — State a clear Definition of Done: "README with 1 screenshot + 3 passing tests + green GitHub Actions."
5. Time box — Estimate time per feature and block it on your calendar.

Copy the checklist straight into the first section of your README. It serves as a compass for where the project is headed.

Cargo Workspace & Directory Design

A single binary with src/main.rs is fine to start. But splitting into "library + CLI" makes testing and reuse easier:

# Cargo.toml
description = "todo CLI"

[workspace]
members = ["crates/todo-core", "crates/todo-cli"]

[workspace.package]
edition = "2021"

[workspace.dependencies]
anyhow = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

project-root/
├── crates/
│   ├── todo-core/      # Business logic (lib)
│   │   └── src/lib.rs
│   └── todo-cli/       # clap-based CLI (bin)
│       └── src/main.rs
├── tests/              # Integration tests
├── fixtures/           # Sample input/output
└── README.md

• The core crate holds pure logic and data models. It's ideal for concentrated unit tests.
• The CLI crate handles clap::Parser, I/O, and filesystem access.
• Write integration tests in tests/ to automate CLI scenario verification with cargo test.

Issues, Branches, and Release Flow

Even for a Rust project, process matters. Here are minimum recommended habits:

1. Issues — Register features, bugs, and docs as separate issues with type and status labels.
2. Branch naming — Use names that reveal intent: feature/todo-add, fix/serde-default.
3. PR template — Four sections are enough: Problem / Solution / Test results / Screenshot.
4. Release notes — Tag releases (v0.1.0), update CHANGELOG.md, and link downloads in the README.

README and Documentation Skeleton

Your README is the project's first impression. Fill in these sections for a professional look:

1. Project description (problem + solution)
2. Quick demo (GIF, screenshot, asciinema link)
3. Installation & usage
4. How to test (cargo test, cargo fmt --check, etc.)
5. Roadmap / TODO
6. License and contribution guide

Optionally, add a /docs folder with API docs or architecture diagrams for the long term.

Project Kickoff Mission

1. Pick one of the five projects and create an issue for it.
2. Choose between a Cargo workspace or single binary, initialize the folder, and run cargo fmt.
3. Write a README draft, .gitignore, and LICENSE, then push the first commit to GitHub.
4. Create scripts/dev.sh and scripts/test.sh to automate repetitive tasks.
5. Draft a user guide that you'll submit (or blog about) at the end of Phase 4. As features are completed, just update the content.

Now it's time to build your own Rust app. The next lesson wraps up the course and points you toward what comes next.