# Commit Convention for Contributing New Lessons to AI Engineering From Scratch > Learn the commit convention for contributing AI Engineering lessons. Discover why one commit per lesson ensures isolated history, CI validation, and curriculum traceability in rohitg00/ai-engineering-from-scratch. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-23 --- **One commit per lesson is enforced to isolate history, enable CI validation, and maintain the 435-lesson curriculum's traceability.** The `rohitg00/ai-engineering-from-scratch` repository maintains a strict commit convention for contributing new lessons to ensure its curriculum remains clean, reproducible, and audit-friendly. Contributions must follow a one-commit-per-lesson policy and use a specific conventional commit format defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). ## Why One Commit Per Lesson Is Enforced The repository treats each lesson as an **atomic unit of work**. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), a pull request that adds ten lessons must contain ten separate commits【AGENTS.md†L40-L41】. This strict enforcement serves three critical purposes. ### Atomic History and Rollback Safety Isolating each lesson into its own commit guarantees that the history of each lesson is independent. If a lesson introduces a regression or content error, maintainers can revert or debug that specific lesson without affecting others. This granularity makes rollback trivial and prevents cross-contamination between curriculum modules. ### CI Validation via audit_lessons.py The enforcement enables the CI audit script [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) to validate each lesson independently【AGENTS.md†L15-L18】. When commits are atomic, the script checks individual lesson directories for compliance—verifying that required subdirectories exist and that content meets quality standards without processing unrelated changes. ### Reviewability and Conflict Prevention Monolithic PRs containing multiple lessons are harder to review and more likely to cause merge conflicts in the curriculum’s tightly-coupled structure. By splitting additions into discrete commits, reviewers focus on one educational concept at a time, and the linear history remains readable. ## The Conventional Commit Format Beyond quantity, the quality of each commit message follows strict conventional commit standards. ### Subject Line Structure The subject line must be **≤ 72 characters** and follow this exact pattern【AGENTS.md†L41-L42】: ``` feat(phase-/): ``` Where `` represents the phase number and `` the lesson number. For example, adding the first lesson of phase one uses: `feat(phase-01/01): add new-lesson`. ### Writing the Commit Body The commit body should describe **why** the lesson is added (its educational goal), not **what** the code does. Explain the learning objective or gap in the curriculum that this lesson fills, rather than listing the files changed. ## Step-by-Step Workflow for Adding a Lesson Follow this workflow to ensure compliance with the commit convention: ```bash # 1. Create the lesson scaffold mkdir -p phases/01-phase-intro/01-new-lesson/{docs,code,tests,outputs} # 2. Add lesson files (docs/en.md, code/main.py, etc.) # … (populate files) … # 3. Stage the new lesson and supporting files git add phases/01-phase-intro/01-new-lesson README.md ROADMAP.md # 4. Commit using the required conventional format git commit -m "feat(phase-01/01): add new-lesson" # 5. Push and open a PR git push -u origin my-new-lesson-branch gh pr create --title "feat(phase-01/01): add new-lesson" \ --body "Introduce the new lesson covering …" ``` Each commit must include the lesson directory plus updates to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) (adding a markdown link) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) (updating the status entry) to maintain curriculum consistency. ## Compliance Checklist: Files That Enforce the Convention Several files work together to maintain this discipline: - **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** – Defines the commit convention and hard rules for the curriculum, including the one-commit-per-lesson mandate. - **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** – CI script that checks each lesson directory for compliance; run this locally before pushing to verify your commit structure. - **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** – Public-facing lesson list; the commit must add a markdown link here for the new lesson. - **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** – Tracks lesson status; the commit must update the roadmap entry for the new lesson. ## Summary - **One commit per lesson directory** is mandatory to maintain atomic history across the 435-lesson curriculum. - The **conventional commit format** `feat(phase-NN/MM): lesson-slug` keeps subject lines under 72 characters and scannable. - The **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** CI script validates each lesson independently, requiring isolated commits to function correctly. - Each commit must update **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** and **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** alongside the lesson content. - Commit messages must explain the **educational goal** (why), not the implementation details (what). ## Frequently Asked Questions ### What happens if I submit multiple lessons in a single commit? Submitting multiple lessons in one commit violates the atomic unit policy defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). The PR will likely be rejected because it prevents [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) from validating lessons independently and complicates rollback if one lesson contains errors. Split your work into separate commits before submitting. ### Why does the commit body need to explain "why" instead of "what"? The "what" is already visible in the code diff. Explaining the **educational goal** helps maintainers understand the pedagogical intent and curriculum flow, ensuring the lesson fits within the 435-lesson progression. This contextual information is preserved in `git log` for future curriculum architects. ### How do I run the audit script locally before pushing? Execute the Python script from the repository root to validate your lesson structure: ```bash python scripts/audit_lessons.py ``` This checks that your lesson directory contains the required `docs`, `code`, `tests`, and `outputs` subdirectories and verifies compliance with the one-commit-per-lesson rule【AGENTS.md†L15-L18】. ### Can I amend a commit if I forget to update README.md or ROADMAP.md? Yes, you should amend the commit to include these files before pushing. The commit must include the lesson directory plus the necessary updates to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) (lesson link) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) (status tracking) to maintain curriculum consistency. Use `git commit --amend` if you haven't pushed yet, or create a fixup commit if you have already pushed to the remote.