# Commit Conventions for Contributing to AI Engineering From Scratch: The Complete Guide > Learn the atomic, conventional commit conventions for AI Engineering From Scratch. Follow the feat(phase-NN/MM): format for consistent contributions to the rohitg00/ai-engineering-from-scratch repo. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-22 --- **AI Engineering From Scratch enforces atomic, conventional commits with a strict `feat(phase-NN/MM): ` format, requiring one commit per lesson directory and simultaneous updates to [`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) to maintain curriculum consistency.** Contributing to the **rohitg00/ai-engineering-from-scratch** repository requires following strict commit conventions designed to keep 435 lessons synchronized with the auto-generated website. These rules ensure that every curriculum change integrates cleanly with the CI pipeline and maintains the repository's pedagogical structure. ## The One Commit Per Lesson Directory Rule Never batch multiple lessons into a single commit. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), each lesson must reside in its own pull request and commit to preserve curriculum integrity. This isolation prevents merge conflicts in the lesson sequencing and allows the automated website builder to parse lesson metadata correctly. The rule applies to every directory under `phases/`, ensuring that each educational unit remains an atomic, reversible unit of work. ## Conventional Commit Format Standards The repository mandates **conventional commit** syntax with specific structural requirements tied to the curriculum's phase and lesson numbering system. ### Subject Line Requirements Every commit subject must follow this exact pattern: - **Type**: Always use `feat` for new lessons - **Scope**: Include phase and lesson identifiers as `(phase-NN/MM)` where NN is the phase number and MM is the lesson number - **Description**: Use a concise slug describing the content - **Length**: Keep the subject line under **72 characters** total Example format: ``` feat(phase-03/05): implement convolutional neural networks ``` ### Commit Body Guidelines The commit body must explain **why** the change is made, not **what** the code does. This contextual information helps maintainers understand the pedagogical intent behind curriculum updates. Keep the body concise but descriptive, avoiding redundant explanations of obvious code changes. ## Atomic Commit Workflow The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) script provides the template for the atomic commit workflow. Follow this exact sequence when contributing new lessons: ```bash # 1. Create a new feature branch git checkout -b add-lesson-phase03-gradient-descent # 2. Edit the lesson files in the appropriate directory # phases/03-computer-vision/03-gradient-descent/ # 3. Stage the lesson directory and roadmap entry git add phases/03-computer-vision/03-gradient-descent \ ROADMAP.md # 4. Commit with the required subject format git commit -m "feat(phase-03/03): gradient descent lesson" # 5. Push and open a PR git push -u origin add-lesson-phase03-gradient-descent gh pr create --title "feat(phase-03/03): gradient descent lesson" \ --body "Adds a new lesson on gradient descent with code, docs, and quiz." ``` This workflow ensures that CI recognises the lesson-specific metadata and triggers the appropriate validation checks. ## Required Documentation Updates Every lesson commit must include simultaneous updates to **README.md** and **ROADMAP.md**. These files drive the auto-generated website and must maintain specific formatting standards. The lesson table row in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) must contain a markdown link using this format: ``` [Lesson Title](phases/NN-phase-slug/MM-lesson-slug/) ``` The same link format applies to status glyphs in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md). Omitting these documentation updates breaks the website build process, as the curriculum generator depends on these markdown tables to construct the navigation structure. ## Generated Files to Exclude Never commit **generated files** such as [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) or [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). As specified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), these artifacts are regenerated automatically by the CI pipeline during the build process. Including generated files in your pull request creates unnecessary merge conflicts and potentially stale data in the repository. The [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) workflow handles all site data generation independently of source commits. ## CI Enforcement and Validation The repository enforces commit conventions through automated checks in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml). This workflow performs audit jobs that validate: - Subject line length (must be ≤ 72 characters) - Conventional commit prefix presence - Proper scope formatting with phase/lesson identifiers - Absence of generated files in the commit Pull requests that fail these checks cannot be merged until the commit history is corrected or rebased to comply with the curriculum standards. ## Summary - **One commit per lesson**: Never batch multiple lessons; each lesson directory requires an isolated commit - **Strict subject format**: Use `feat(phase-NN/MM): ` with a maximum of 72 characters - **Explain intent**: The commit body must clarify why changes are made, not what the code does - **Documentation coupling**: Always include [`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) updates in the same commit with proper markdown link formatting - **Exclude artifacts**: Never commit [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) or [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js); these are CI-generated - **Atomic workflow**: Stage the lesson directory and documentation files together before committing ## Frequently Asked Questions ### What happens if I accidentally batch multiple lessons into one commit? According to the hard rules in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), batching lessons violates the atomic commit policy and will cause the CI audit to fail. You must rebase your branch to separate the lessons into individual commits, each containing only one lesson directory and its corresponding documentation updates. ### Can I use commit types other than 'feat' for lesson contributions? The commit conventions for contributing to AI Engineering From Scratch require the `feat` prefix for all new lesson content. Other conventional commit types like `fix`, `docs`, or `refactor` may be used for corrections or infrastructure changes, but new lessons must always use `feat` to trigger the correct curriculum indexing logic. ### Why must I update ROADMAP.md in the same commit as the lesson? The [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) file contains status glyphs and links that feed the website generator. Committed separately, the documentation and lesson code could fall out of sync, breaking the auto-generated website. The atomic requirement ensures that the curriculum metadata and source content always remain consistent. ### How do I fix a commit message that exceeds the 72-character limit? If your initial commit violates the subject line length requirement, use `git commit --amend` to rewrite the message before pushing, or perform an interactive rebase (`git rebase -i HEAD~N`) if the commit has already been pushed. The CI pipeline in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) will reject any commits with subjects longer than 72 characters.