Commit Conventions for Contributing to AI Engineering From Scratch: The Complete Guide

AI Engineering From Scratch enforces atomic, conventional commits with a strict feat(phase-NN/MM): <slug> format, requiring one commit per lesson directory and simultaneous updates to README.md and ROADMAP.md to maintain curriculum consistency.

Contributing to the rohitg00/ai-engineering-from-scratch repository requires following strict commit conventions designed to keep 435 lessons synchronized with the auto-generated website. These rules ensure that every curriculum change integrates cleanly with the CI pipeline and maintains the repository's pedagogical structure.

The One Commit Per Lesson Directory Rule

Never batch multiple lessons into a single commit. According to AGENTS.md, each lesson must reside in its own pull request and commit to preserve curriculum integrity.

This isolation prevents merge conflicts in the lesson sequencing and allows the automated website builder to parse lesson metadata correctly. The rule applies to every directory under phases/, ensuring that each educational unit remains an atomic, reversible unit of work.

Conventional Commit Format Standards

The repository mandates conventional commit syntax with specific structural requirements tied to the curriculum's phase and lesson numbering system.

Subject Line Requirements

Every commit subject must follow this exact pattern:

• Type: Always use feat for new lessons
• Scope: Include phase and lesson identifiers as (phase-NN/MM) where NN is the phase number and MM is the lesson number
• Description: Use a concise slug describing the content
• Length: Keep the subject line under 72 characters total

Example format:

feat(phase-03/05): implement convolutional neural networks

Commit Body Guidelines

The commit body must explain why the change is made, not what the code does. This contextual information helps maintainers understand the pedagogical intent behind curriculum updates. Keep the body concise but descriptive, avoiding redundant explanations of obvious code changes.

Atomic Commit Workflow

The scripts/scaffold-lesson.sh script provides the template for the atomic commit workflow. Follow this exact sequence when contributing new lessons:

# 1. Create a new feature branch

git checkout -b add-lesson-phase03-gradient-descent

# 2. Edit the lesson files in the appropriate directory

# phases/03-computer-vision/03-gradient-descent/

# 3. Stage the lesson directory and roadmap entry

git add phases/03-computer-vision/03-gradient-descent \
        ROADMAP.md

# 4. Commit with the required subject format

git commit -m "feat(phase-03/03): gradient descent lesson"

# 5. Push and open a PR

git push -u origin add-lesson-phase03-gradient-descent
gh pr create --title "feat(phase-03/03): gradient descent lesson" \
             --body "Adds a new lesson on gradient descent with code, docs, and quiz."

This workflow ensures that CI recognises the lesson-specific metadata and triggers the appropriate validation checks.

Required Documentation Updates

Every lesson commit must include simultaneous updates to README.md and ROADMAP.md. These files drive the auto-generated website and must maintain specific formatting standards.

The lesson table row in README.md must contain a markdown link using this format:

[Lesson Title](phases/NN-phase-slug/MM-lesson-slug/)

The same link format applies to status glyphs in ROADMAP.md. Omitting these documentation updates breaks the website build process, as the curriculum generator depends on these markdown tables to construct the navigation structure.

Generated Files to Exclude

Never commit generated files such as catalog.json or site/data.js. As specified in AGENTS.md, these artifacts are regenerated automatically by the CI pipeline during the build process.

Including generated files in your pull request creates unnecessary merge conflicts and potentially stale data in the repository. The .github/workflows/curriculum.yml workflow handles all site data generation independently of source commits.

CI Enforcement and Validation

The repository enforces commit conventions through automated checks in .github/workflows/curriculum.yml. This workflow performs audit jobs that validate:

• Subject line length (must be ≤ 72 characters)
• Conventional commit prefix presence
• Proper scope formatting with phase/lesson identifiers
• Absence of generated files in the commit

Pull requests that fail these checks cannot be merged until the commit history is corrected or rebased to comply with the curriculum standards.

Summary

• One commit per lesson: Never batch multiple lessons; each lesson directory requires an isolated commit
• Strict subject format: Use feat(phase-NN/MM): <slug> with a maximum of 72 characters
• Explain intent: The commit body must clarify why changes are made, not what the code does
• Documentation coupling: Always include README.md and ROADMAP.md updates in the same commit with proper markdown link formatting
• Exclude artifacts: Never commit catalog.json or site/data.js; these are CI-generated
• Atomic workflow: Stage the lesson directory and documentation files together before committing

Frequently Asked Questions

What happens if I accidentally batch multiple lessons into one commit?

According to the hard rules in AGENTS.md, batching lessons violates the atomic commit policy and will cause the CI audit to fail. You must rebase your branch to separate the lessons into individual commits, each containing only one lesson directory and its corresponding documentation updates.

Can I use commit types other than 'feat' for lesson contributions?

The commit conventions for contributing to AI Engineering From Scratch require the feat prefix for all new lesson content. Other conventional commit types like fix, docs, or refactor may be used for corrections or infrastructure changes, but new lessons must always use feat to trigger the correct curriculum indexing logic.

Why must I update ROADMAP.md in the same commit as the lesson?

The ROADMAP.md file contains status glyphs and links that feed the website generator. Committed separately, the documentation and lesson code could fall out of sync, breaking the auto-generated website. The atomic requirement ensures that the curriculum metadata and source content always remain consistent.

How do I fix a commit message that exceeds the 72-character limit?

If your initial commit violates the subject line length requirement, use git commit --amend to rewrite the message before pushing, or perform an interactive rebase (git rebase -i HEAD~N) if the commit has already been pushed. The CI pipeline in .github/workflows/curriculum.yml will reject any commits with subjects longer than 72 characters.

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