Conventional Commit Format for Contributing Lessons to ai-engineering-from-scratch

When contributing a new lesson to ai-engineering-from-scratch, use the format feat(phase-NN/MM): <slug> with a subject line ≤72 characters, where NN is the phase number, MM is the lesson number, and matches the lesson directory name.

The ai-engineering-from-scratch repository enforces a strict conventional commit format to keep curriculum history clean and machine-readable. This convention is defined in AGENTS.md (lines 40-42) as a "Hard rule" and ensures that every lesson addition follows a predictable pattern that automated tools can parse for changelog generation and README synchronization.

Conventional Commit Subject Format

The subject line must follow this exact pattern:

feat(phase-NN/MM): <slug>

• Type: Always use feat to indicate a new feature (the lesson).
• Scope: (phase-NN/MM) pinpoints the exact curriculum location, where NN is the two-digit phase number and MM is the two-digit lesson number.
• Description: <slug> is a short, hyphen-separated identifier that must match the lesson directory name (e.g., softmax-implementation).

The entire subject line must not exceed 72 characters. This constraint ensures readability in Git logs and prevents truncation in GitHub interfaces.

Matching Directory Structure

The slug in your commit must correspond exactly to the directory structure under phases/NN-phase-slug/MM-lesson-slug/. For example, if you are adding lesson 03 in phase 05 about softmax implementation, your directory is phases/05-phase-slug/03-softmax-implementation/, and your commit subject must be feat(phase-05/03): softmax-implementation.

Writing the Commit Body

Unlike typical commit messages that describe what changed, the body of a lesson commit should explain why the lesson is added. Describe the learning goals, the concepts covered, and the educational purpose.

This "why-first" approach provides curriculum provenance for learners and educators reviewing the project history. It also prevents redundancy since the code itself shows what was implemented.

Complete Commit Example

Here is the complete workflow for adding a lesson:

# Stage the new lesson directory

git add phases/05-phase-slug/03-softmax-implementation

# Commit with conventional format and descriptive body

git commit -m "feat(phase-05/03): softmax-implementation" -m "Adds a step-by-step walkthrough of the softmax function, including math derivation and a reference Python implementation."

# Push to your branch

git push origin your-branch

Key points in this example:

• The first -m flag creates the subject line adhering to the feat(phase-NN/MM): <slug> pattern.
• The second -m flag adds the body explaining pedagogical intent.
• The slug softmax-implementation matches the directory name exactly.

Automation and Validation

The repository uses this conventional commit format to power several automation workflows:

• Changelog generation: CI scripts parse the feat type and scope to categorize curriculum additions.
• README synchronization: The slug extracted from commits automatically updates README.md with lesson links.
• Local validation: Run scripts/audit_lessons.py before pushing to verify your commit follows the required conventions.

These automations depend on strict adherence to the format defined in AGENTS.md. Deviations break the CI pipeline and require manual correction.

Summary

• Use the format feat(phase-NN/MM): <slug> for every new lesson commit.
• Limit subject lines to 72 characters for optimal readability.
• Ensure the slug matches the lesson directory name under phases/NN-phase-slug/MM-lesson-slug/.
• Explain learning goals and educational purpose in the commit body, not implementation details.
• Validate commits locally using scripts/audit_lessons.py before pushing.
• Follow this convention to enable automatic changelog updates and README synchronization.

Frequently Asked Questions

What happens if I exceed the 72-character limit in the commit subject?

The commit will fail the validation checks in scripts/audit_lessons.py and CI pipelines. The 72-character limit ensures clean Git history and prevents truncation in GitHub interfaces. Keep slugs concise and phase/lesson numbers properly formatted.

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

No. The ai-engineering-from-scratch repository specifically requires feat for new lessons as defined in AGENTS.md. Other types like fix, docs, or chore are reserved for maintenance tasks, bug fixes, or documentation updates outside the curriculum structure.

How does the slug in the commit message relate to the file structure?

The slug must exactly match the lesson directory name. For lesson 03 in phase 05 stored at phases/05-phase-slug/03-softmax-implementation/, the commit subject must end with : softmax-implementation. This allows CI scripts to locate the lesson content and update README.md automatically.

Why should the commit body explain "why" rather than "what"?

The code and file structure already show what was implemented. Explaining the pedagogical intent—such as learning objectives and concept coverage—creates valuable curriculum provenance for educators and learners reviewing the Git history. This approach aligns with the repository's educational mission and distinguishes lesson commits from standard code commits.

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