# How to Create a New Community Exercise for Rustlings: A Complete Guide

> Learn how to create a new community exercise for Rustlings. Follow our complete guide to add starter files, solutions, and metadata to contribute to the Rustlings project.

- Repository: [The Rust Programming Language/rustlings](https://github.com/rust-lang/rustlings)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To create a new community exercise for Rustlings, you must add a starter file containing a `// TODO:` comment in `exercises/<topic>/`, create a matching solution in `solutions/<topic>/`, register the exercise metadata in [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml), and update the topic's README with relevant learning resources.**

The `rust-lang/rustlings` repository is an open-source collection of small exercises designed to help developers learn Rust. When you create a new community exercise for Rustlings, you are contributing to a structured learning path that thousands of beginners use daily. This guide walks through the exact file locations, metadata requirements, and validation steps needed to submit a working exercise.

## Understanding the Rustlings Exercise Structure

Rustlings organizes learning tasks as **exercises**, each consisting of a paired file system:

- **Exercise file**: The starter code presented to learners, located at `exercises/<topic>/<topic>N.rs`. This file must contain a `// TODO:` comment indicating where the learner should write code.
- **Solution file**: A fully working reference implementation stored at `solutions/<topic>/<topic>N.rs`. The test harness uses this file to verify that exercises can be completed correctly.

The `rustlings-macros` crate reads exercise metadata at compile time from [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) to build the list displayed by the CLI.

## Step-by-Step Guide to Creating a Community Exercise

### Step 1: Create the Starter Exercise File

Create your exercise file in the appropriate topic directory under `exercises/`. If your topic does not exist, create a new folder following the existing naming conventions.

The starter file must include a `// TODO:` comment that clearly instructs the learner what to implement.

```rust
// exercises/mytopic/mytopic1.rs

fn main() {
    // TODO: Print the message "Hello, Rustlings!" to the console.
}

```

### Step 2: Write the Solution File

Create a corresponding solution file in the `solutions/` directory that mirrors the exercise file path. This file should contain a complete, working implementation with comments explaining the correct approach.

```rust
// solutions/mytopic/mytopic1.rs

fn main() {
    // The println! macro handles string output to stdout
    println!("Hello, Rustlings!");
}

```

### Step 3: Register the Exercise in info.toml

Add your exercise to the [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) file. This TOML file is parsed at compile time to generate the exercise registry. Each exercise requires a `[[exercises]]` table with specific fields.

```toml
[[exercises]]
name = "mytopic1"
dir = "mytopic"
hint = """
Use the `println!` macro to output a string literal.
Check the standard library documentation for the correct syntax.
"""

```

If your exercise does not include a separate test file, add `test = false` to the table.

### Step 4: Update the Topic README

Create or modify `exercises/<topic>/README.md` to provide context for your topic. Include a short description of the concept being taught and links to relevant chapters in *The Rust Book*.

```markdown

# MyTopic – Learning the Basics of X

This exercise introduces **X**, a fundamental Rust concept.  
Read the relevant chapter in *The Rust Book*:  
https://doc.rust-lang.org/book/chXX-YY.html

```

### Step 5: Test Your Exercise

Validate your exercise using the Rustlings CLI and the test suite before submitting.

Run the specific exercise to ensure it fails initially (as expected) and passes after implementing the solution:

```bash
cargo run -- run mytopic1

```

Execute the full test suite to verify that your metadata registration is correct and that all files compile:

```bash
cargo test

```

## Key Files and Their Roles

| File | Role |
|------|------|
| [`CONTRIBUTING.md`](https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md) | Official contribution guide containing the *Adding an exercise* section with detailed requirements. |
| [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) | Central registry parsed by the `rustlings-macros` crate at compile time to build the exercise list. |
| `exercises/<topic>/<topic>N.rs` | Starter code presented to learners; must contain a `// TODO:` comment. |
| `solutions/<topic>/<topic>N.rs` | Reference implementation used by the test harness to verify correctness. |
| `exercises/<topic>/README.md` | Learning resources and links to the Rust Book for the specific topic. |
| [`src/main.rs`](https://github.com/rust-lang/rustlings/blob/main/src/main.rs) | CLI entry point that loads metadata and executes exercise commands. |
| `tests/` | Integration tests ensuring every registered exercise compiles and runs correctly. |

## Summary

- **Create paired files**: Add a starter file in `exercises/<topic>/` with a `// TODO:` comment and a working solution in `solutions/<topic>/`.
- **Register metadata**: Add a `[[exercises]]` entry to [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) with the exercise name, directory, and hint.
- **Document the topic**: Update `exercises/<topic>/README.md` with descriptions and links to the Rust Book.
- **Validate locally**: Run `cargo run -- run <exercise>` and `cargo test` to ensure the exercise behaves correctly before submitting a Pull Request.

## Frequently Asked Questions

### What is the minimum required metadata for a new exercise?

You must add a `[[exercises]]` table to [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) containing at least the `name` and `dir` fields. The `name` field matches the exercise filename without the `.rs` extension, and `dir` specifies the topic folder. You should also include a `hint` field to guide learners when they are stuck.

### Can I create a new topic folder or should I use existing ones?

You can create a new topic folder under `exercises/` if your exercise covers a concept not addressed by existing topics. Name the folder descriptively (e.g., `advanced_generics` or `error_handling`). Ensure you create a corresponding folder under `solutions/` with the same name, and add a [`README.md`](https://github.com/rust-lang/rustlings/blob/main/README.md) to the new topic folder explaining the concept and linking to relevant Rust Book chapters.

### How do I ensure my exercise appears in the correct order in the Rustlings CLI?

The Rustlings CLI displays exercises in the order they appear in [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml). To position your exercise correctly, insert the `[[exercises]]` entry in the TOML file at the desired sequence point. The `rustlings-macros` crate processes this file at compile time to generate the ordered exercise list used by the CLI in [`src/main.rs`](https://github.com/rust-lang/rustlings/blob/main/src/main.rs).

### What testing commands validate that my exercise works correctly?

Run `cargo run -- run <exercise_name>` to execute a specific exercise and verify it fails initially (showing the TODO) and passes after you implement the solution. Then run `cargo test` to execute the full integration test suite, which validates that all registered exercises compile, that solutions exist for each exercise, and that the metadata in [`rustlings-macros/info.toml`](https://github.com/rust-lang/rustlings/blob/main/rustlings-macros/info.toml) is correctly formatted.