Curriculum Authoring Guide

Curriculum Authoring Guide

Curriculum is a learner-facing compatibility contract. Treat an exercise name and its position in info.toml as stable once learners can use it. Do not rename, reorder, or remove an exercise without an explicit migration.

Change the complete exercise set

For each added or changed exercise, keep these files synchronized:

1. exercises/<topic>/<name>.py contains the learner-edited, intentionally incomplete exercise.
2. checks/<topic>/<name>.py mirrors the exercise path and contains its checks.
3. solutions/<name>.py is the reference-solution loader.
4. solutions/_answers.py contains the corresponding reference answer.
5. info.toml contains the ordered manifest entry, hint, and documentation URL.

The manifest derives a check path by replacing the exercise path's exercises/ prefix with checks/. Keep the topic directory and filename identical on both sides.

Write for learners

• Keep the # I AM NOT DONE marker in learner exercise files.
• Keep exercises self-contained because they are copied into learner workspaces.
• Use bare assertions in checks with actionable, beginner-facing messages.
• Make the hint describe a useful next step without replacing the exercise.
• Keep the reference answer separate from the learner exercise.

Validate before proposing a change

From the repository root, run the curriculum-specific verification:

python -m pytest tests/integration/test_solution_verify.py -q

Also run the required repository validation:

python -m pytest -q
pythonlings --root tests/fixtures/passing_curriculum verify

Confirm that each changed learner exercise still has its pending marker and that its mirrored check, solution loader, answer, and manifest entry all agree. For packaging, workspace, or curriculum distribution changes, follow the additional build and installed-flow validation in AGENTS.md.