Commit Conventions for Adding New Lessons to AI Engineering From Scratch

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): <slug>, limit subject lines to 72 characters, and always update README.md and 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 and the CI pipeline defined in 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#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, outputs/, etc.)
• Updates to README.md with the lesson link
• Updates to ROADMAP.md with status glyphs

This atomicity allows 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): <slug>

Where:

• NN represents the phase number (e.g., 02 for phase 2)
• MM represents the lesson number within that phase
• <slug> 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:

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#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 CI failures.

Practical Workflow Example

Follow this exact sequence when committing a new lesson:

# 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: Validates that the lesson structure follows the directory conventions and that commit messages match the required pattern
• curriculum.yml: The CI pipeline checks that 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 updates, and ROADMAP.md updates
• Strict format: Use feat(phase-NN/MM): <slug> 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 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): <description> 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, 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 and the 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 to verify your lesson structure and commit format. Additionally, you should run the site build process to confirm that your README.md markdown links parse correctly and that ROADMAP.md status glyphs render as expected.

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