Commit Convention for Contributing New Lessons to AI Engineering From Scratch

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.

Why One Commit Per Lesson Is Enforced

The repository treats each lesson as an atomic unit of work. According to 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 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-<NN>/<MM>): <lesson-sllug>

Where <NN> represents the phase number and <MM> 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:

# 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 (adding a markdown link) and 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 – Defines the commit convention and hard rules for the curriculum, including the one-commit-per-lesson mandate.
• 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 – Public-facing lesson list; the commit must add a markdown link here for the new lesson.
• 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 CI script validates each lesson independently, requiring isolated commits to function correctly.
• Each commit must update README.md and 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. The PR will likely be rejected because it prevents 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:

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 (lesson link) and 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.

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