# Conventional Commit Format for Contributing Lessons to ai-engineering-from-scratch > Learn the conventional commit format feat(phase-NN/MM): for contributing lessons to ai-engineering-from-scratch. Ensure shorter subject lines and clear commit messages for smooth contributions. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-14 --- **When contributing a new lesson to ai-engineering-from-scratch, use the format `feat(phase-NN/MM): ` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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): ``` - **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**: `` 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: ```bash # 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): ` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) with lesson links. - **Local validation**: Run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Deviations break the CI pipeline and require manual correction. ## Summary - Use the format `feat(phase-NN/MM): ` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.