# Commit Message Conventions for Contributing Lessons to AI Engineering from Scratch > Learn Conventional Commits for AI engineering contributions. Follow the feat(phase-NN/MM): format to submit lessons effectively to the ai-engineering-from-scratch repository. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-05 --- **Contributors must use the Conventional Commits format `feat(phase-NN/MM): ` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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: ```bash 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml). The workflow executes [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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: ```bash # 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: ```bash 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) automatically. Additionally, [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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): ` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) - Proper formatting enables automatic updates to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and site generation via [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at the repository root (specifically lines 40-42), with enforcement logic implemented in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and the [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) CI configuration.