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

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, 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 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.

// 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.

// 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 file. This TOML file is parsed at compile time to generate the exercise registry. Each exercise requires a [[exercises]] table with specific fields.

[[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.

# 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:

cargo run -- run mytopic1

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

cargo test

Key Files and Their Roles

File	Role
CONTRIBUTING.md	Official contribution guide containing the Adding an exercise section with detailed requirements.
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	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 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 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 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. 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.

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 is correctly formatted.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}