Conventional Commit Format Requirement for rohitg00/ai-engineering-from-scratch

The repository enforces a strict Conventional Commit format where every commit subject must follow feat(phase-NN/MM): <slug>, be 72 characters or fewer, and explain the "why" not the "what" in the body.

The rohitg00/ai-engineering-from-scratch curriculum repository requires all contributors to follow a machine-readable commit convention. This standardized format, defined in the project's AGENTS.md file, ensures that the lesson history remains clean, searchable, and automatically parseable across the AI engineering curriculum.

Conventional Commit Structure

Required Subject Line Format

Every commit message must adhere to a strict pattern in the subject line:

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

• feat – The commit type, which must always be "feat" when adding new lessons according to the source code.
• phase-NN/MM – The phase number (NN) and lesson number (MM) identifiers.
• <slug> – A short, hyphen-separated description of the lesson content (e.g., add-gradient-descent).

The entire subject line must not exceed 72 characters, including the type, scope, and description.

Commit Message Body Rules

The commit body should explain why the change is necessary, avoiding descriptions of what the code does. This distinction helps reviewers understand the pedagogical intent behind new curriculum additions without reading the diffs.

Valid and Invalid Commit Examples

Correct commit subject

feat(phase-14/42): add-agent-workbench-capstone

This example follows all rules: it uses the feat type, specifies the phase and lesson numbers correctly, keeps the slug descriptive yet concise, and stays under the 72-character limit.

Incorrect commit subjects

The following patterns violate the repository's conventional commit format requirement:

• Too long: Exceeding 72 characters in the subject line.
• Wrong type: Using fix(...), docs(...), or other types instead of feat.
• Missing scope: Omitting the phase/lesson specification (e.g., feat: add-new-lesson).

Implementation in Git Workflow

When contributing to rohitg00/ai-engineering-from-scratch, apply the format directly in your Git commands:

git checkout -b add-agent-workbench-capstone

# ... make changes ...

git add .
git commit -m "feat(phase-14/42): add-agent-workbench-capstone" -m "Add the full Agent Workbench capstone lesson, including docs, code, and outputs. This lesson demonstrates multi-session handoff."
git push origin add-agent-workbench-capstone

The -m flag appears twice: first for the subject line, then for the body explaining the pedagogical rationale.

Where This Rule Is Defined

The conventional commit format requirement is codified in three key files:

• AGENTS.md (lines 40-42): Contains the "Hard rules" section that specifies the exact feat(phase-NN/MM): <slug> pattern and the 72-character limit.
• CONTRIBUTING.md: Reinforces the commit style guidelines for pull request submissions.
• README.md: Displays the public-facing lesson table, where each entry must be added via a properly formatted commit to maintain curriculum integrity.

Summary

• Commit subjects must follow the exact pattern: feat(phase-NN/MM): <slug>.
• Subject lines are limited to 72 characters maximum.
• The commit type must be feat for all new lesson contributions.
• Commit bodies must explain the why, not the what.
• These rules are enforced via the AGENTS.md "Hard rules" section.

Frequently Asked Questions

What happens if my commit message exceeds 72 characters?

Commits with subject lines longer than 72 characters violate the repository's hard rules as specified in AGENTS.md. You must amend your commit using git commit --amend to shorten the subject before submitting a pull request.

Can I use other Conventional Commit types like fix or docs?

No. According to the AGENTS.md source code, the commit type must always be feat when adding new lessons to the curriculum. Other types such as fix, docs, or chore do not conform to the specific conventional commit format requirement for this repository.

How do I determine the correct phase and lesson numbers?

The phase (NN) and lesson (MM) numbers correspond to the curriculum's structured progression. These identifiers must match the lesson's position in the repository's README.md table, ensuring consistent navigation through the AI engineering course materials.

Where can I find the official commit format specification?

The official specification resides in the AGENTS.md file at the repository root, specifically within the "Hard rules" section (lines 40-42). This document serves as the authoritative source for all conventional commit format requirements in rohitg00/ai-engineering-from-scratch.

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