# Commit Conventions for Adding New Lessons to AI Engineering From Scratch > Learn the recommended commit conventions for adding new lessons to the ai-engineering-from-scratch repository. Follow feat(phase-NN/MM): format and update README and ROADMAP. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-18 --- **When adding new lessons to the ai-engineering-from-scratch repository, you must use atomic commits with the conventional commit format `feat(phase-NN/MM): `, limit subject lines to 72 characters, and always 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) in the same commit.** The `rohitg00/ai-engineering-from-scratch` curriculum relies on strict commit conventions to power automated tooling and maintain synchronization across documentation. Following these rules ensures that scripts like [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and the CI pipeline defined in [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml) can correctly parse new content without manual intervention. ## Atomic Commit Structure (One Commit Per Lesson) Every new lesson must be introduced in a **single atomic commit** that encompasses the entire lesson directory. According to [[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md#L40-L42), batching multiple lessons into one commit is prohibited. An atomic commit for a lesson includes: - The lesson directory structure (`docs/`, `code/`, [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), `outputs/`, etc.) - Updates to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) with the lesson link - Updates to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) with status glyphs This atomicity allows [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to detect curriculum changes reliably and ensures lesson counts remain accurate across the repository. ## Conventional Commit Format The commit subject line must follow a precise conventional commit pattern to signal automated systems that a new curriculum feature is being added. **Required format:** ``` feat(phase-NN/MM): ``` Where: - `NN` represents the phase number (e.g., `02` for phase 2) - `MM` represents the lesson number within that phase - `` is a brief description (e.g., `add-dqn-lesson`) **Critical constraints:** - **Subject length**: Maximum 72 characters to prevent truncation in GitHub and Git tooling - **Prefix restriction**: Use only `feat:` when adding lessons. Do not prepend `fix:`, `chore:`, or other prefixes, as these signal different change types that may bypass curriculum validation - **Body content**: Explain *why* the change is made, not *what* the change does. Describe the pedagogical intent or gap the lesson fills Example commit message: ```text feat(phase-02/09): add DQN lesson Introduces a Deep Q-Network implementation from first principles to expand the reinforcement learning section of phase 2. ``` ## Required Documentation Updates After staging the lesson files, you must update cross-reference documentation before committing. As specified in [[`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md#L7-L21), every lesson commit must include: 1. **README.md updates**: Add the lesson title and markdown link (`[Title](phases/.../...)`) 2. **ROADMAP.md updates**: Modify the appropriate row to reflect the lesson's status using the project's glyph system 3. **Verification**: Run the CI-generated site build locally to confirm markdown links parse correctly Failing to include these files in the same commit breaks the automated lesson counting and causes [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml) CI failures. ## Practical Workflow Example Follow this exact sequence when committing a new lesson: ```bash # 1. Create the lesson directory structure mkdir -p phases/02-ml-fundamentals/09-dqn-lesson/{docs,code,outputs} # 2. Add lesson content files (docs/lesson.md, code/train.py, quiz.json, etc.) # 3. Stage the atomic commit including documentation updates git add phases/02-ml-fundamentals/09-dqn-lesson \ README.md \ ROADMAP.md # 4. Commit with the required conventional format git commit -m "feat(phase-02/09): add DQN lesson" \ -m "Introduces a DQN implementation from first principles, together with" \ -m "unit tests and a quiz. The lesson expands the reinforcement-learning" \ -m "section of phase 2." # 5. Push and create PR git push origin your-branch-name gh pr create --title "feat(phase-02/09): add DQN lesson" \ --body "Adds a new Deep Q-Network lesson (phase 2, lesson 9)." ``` ## Validation and Automation The repository includes automated safeguards to enforce these conventions. Before opening a pull request, verify your commit using: - **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)**: Validates that the lesson structure follows the directory conventions and that commit messages match the required pattern - **[`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml)**: The CI pipeline checks that [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) lesson counts match the actual number of lesson directories and that all links resolve correctly These scripts depend on the strict `feat(phase-NN/MM)` format to differentiate curriculum additions from maintenance changes. ## Summary - **Atomic commits**: Each lesson must be a single commit containing the lesson directory, [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) updates, and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) updates - **Strict format**: Use `feat(phase-NN/MM): ` with a maximum 72-character subject line - **No prefix variation**: Always use `feat:`; never use `fix:`, `chore:`, or other conventional commit types for new lessons - **Explain why**: The commit body should describe the pedagogical rationale, not the file changes - **Automated validation**: Run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) locally to verify compliance before submitting your PR ## Frequently Asked Questions ### What is the exact commit message format for new lessons? You must use `feat(phase-NN/MM): ` where `NN` is the phase number and `MM` is the lesson number. For example: `feat(phase-02/09): add DQN lesson`. The subject must be 72 characters or fewer and the body should explain why the lesson is being added. ### Can I use fix: or chore: prefixes when adding lessons? No. According to the hard rules in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), you must use only the `feat:` prefix when adding new lessons. Other prefixes signal different change types to the automated tooling and may cause the curriculum validation scripts to miss your lesson entirely. ### Why must I update README.md and ROADMAP.md in the same commit? These files contain the public lesson index and status tracking that drive the autogenerated website. Updating them in the same atomic commit ensures that [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and the [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml) CI pipeline can verify link integrity and maintain accurate lesson counts automatically. Splitting these changes into separate commits breaks the synchronization logic. ### How do I validate my commit before opening a PR? Run the local audit script [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) to verify your lesson structure and commit format. Additionally, you should run the site build process to confirm that your [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) markdown links parse correctly and that [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status glyphs render as expected.