Commit Message Conventions for Contributing Lessons to AI Engineering from Scratch

Contributors must use the Conventional Commits format feat(phase-NN/MM): <description> with a subject line under 72 characters, limiting each commit to a single lesson directory.

The rohitg00/ai-engineering-from-scratch repository maintains strict commit message conventions for contributing lessons to ensure automated curriculum management and clean project history. These standards, defined in the project's operating manual AGENTS.md, enforce atomic commits that directly map to lesson directories within the phased curriculum structure.

The Conventional Commits Format

Every commit message must follow the pattern specified in AGENTS.md (lines 40-42). The required format uses a structured prefix identifying the phase and lesson number.

• Prefix structure: feat(phase-NN/MM): where NN represents the two-digit phase number and MM the two-digit lesson number
• Subject line: Maximum 72 characters describing what was added, not why
• Semantics: The subject describes the action (e.g., "add gradient-descent lesson") while the optional body provides rationale

Subject Line Requirements

Keep the subject concise and actionable. The message should complete the sentence: "This commit will..." Avoid explanations or context in the subject; reserve those details for the commit body if necessary.

One-Commit-Per-Lesson Rule

The repository enforces atomic commits that correspond exactly to individual lesson directories. Each lesson residing in phases/XX-phase-slug/YY-lesson-slug/ requires its own isolated commit.

This rule prevents batching multiple lessons into a single commit. For example, when adding the agent workbench capstone in phase 14, you must execute:

git add phases/14-agent-engineering/42-agent-workbench-capstone
git commit -m "feat(phase-14/42): add agent-workbench-capstone"

No other lesson directories may be included in the same commit.

Validation and CI Enforcement

Non-compliant commits are blocked by the CI pipeline defined in .github/workflows/curriculum.yml. The workflow executes scripts/audit_lessons.py to validate both lesson structure and commit message formatting before allowing merges.

If the audit detects malformed prefixes, incorrect phase/lesson numbering, or batched lessons covering multiple directories, the pull request fails checks and cannot merge into main.

Practical Commit Examples

When adding a new lesson, stage only the specific lesson directory and commit using the required format:

# Create and populate lesson directory

mkdir -p phases/03-ml-fundamentals/07-gradient-descent/{docs,code,outputs}

# ... add content ...

# Atomic commit for single lesson

git add phases/03-ml-fundamentals/07-gradient-descent
git commit -m "feat(phase-03/07): add gradient-descent lesson"

To fix a malformed commit message before pushing:

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

Automated Curriculum Integration

These conventions directly power the repository's automation systems. According to the source code, the CI pipeline extracts lesson metadata from compliant commit messages to synchronize README.md and ROADMAP.md automatically.

Additionally, site/build.js parses these files to generate the project website. Deviation from the expected format breaks site data generation, causing deployment failures and breaking the automated changelog.

Summary

• Use the format feat(phase-NN/MM): <description> for all lesson commits
• Limit subject lines to 72 characters describing what was added
• Commit exactly one lesson per commit, corresponding to one directory in phases/
• Validation occurs via scripts/audit_lessons.py in .github/workflows/curriculum.yml
• Proper formatting enables automatic updates to README.md, ROADMAP.md, and site generation via site/build.js

Frequently Asked Questions

What happens if I include multiple lessons in one commit?

The CI pipeline will reject the pull request. The audit_lessons.py script flags batched commits as non-compliant, preventing merge until you split changes into atomic commits, one per lesson directory.

Can I use commit types other than feat for lessons?

According to AGENTS.md, new lessons require the feat prefix to trigger the automated changelog and roadmap updates. Other conventional commit types may not properly activate the curriculum synchronization scripts that maintain README.md and ROADMAP.md.

How do I fix a commit message after I've already pushed it?

Use git commit --amend -m "feat(phase-NN/MM): corrected message" if unpushed, or perform an interactive rebase with git rebase -i HEAD~N to rewrite history for already-pushed commits, then force push to your feature branch.

Where are these rules officially documented?

The hard rules reside in AGENTS.md at the repository root (specifically lines 40-42), with enforcement logic implemented in scripts/audit_lessons.py and the .github/workflows/curriculum.yml CI configuration.

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