# Commit Rules for Contributing to AI Engineering from Scratch > Discover the commit rules for contributing to the AI engineering from scratch repository. Learn about single commits per lesson, conventional commits, and atomic workflows for efficient contributions. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-21 --- **The repository enforces three strict commit rules defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md): one commit per lesson directory, conventional commit subjects following the `feat(phase-NN/MM): ` pattern, and an atomic workflow that stages lesson files alongside [`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.** Contributors to the `rohitg00/ai-engineering-from-scratch` curriculum must follow specific commit rules to maintain a clean, auditable history. These guidelines, documented in the **Hard rules** section of [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), ensure that every lesson can be tracked, reviewed, and rolled back independently without affecting the broader codebase. ## Where Commit Rules Are Documented The authoritative source for all commit policies resides in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at the repository root. This file contains the **Hard rules** section that mandates the one-commit-per-lesson requirement and the **New-lesson onboarding** section that details the exact `git add` and `git commit` commands required for contributions. ## The Three Core Commit Rules ### One Commit Per Lesson Directory Each pull request must contain a separate commit for every lesson added or modified. If a PR introduces ten lessons, it must include ten distinct commits. This granularity guarantees fine-grained history and enables maintainers to roll back a single lesson without cascading effects on unrelated content. ### Conventional Commit Subjects Commit titles must follow the pattern `feat(phase-NN/MM): ` and remain under **72 characters**. The commit body must describe *why* the change is made rather than *what* the code does. This convention supports automated tooling like changelog generators and provides reviewers with immediate contextual understanding. ### Atomic Commit Workflow Contributors must stage the lesson directory, [`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) in a single `git add` command before committing. This atomic approach ensures that the three required source locations—the lesson files, the public index, and the roadmap status—remain perfectly synchronized in the repository history. ## Practical Contribution Workflow When adding a new lesson, follow this exact sequence defined in the **New-lesson onboarding** section: 1. Create the lesson folder structure: ```bash mkdir -p phases/12-multimodal-ai/03-example-lesson/{docs,code,tests,outputs} ``` 2. Write the lesson content, including documentation, code, and tests. 3. Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) with a new row in the lessons table and modify [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to reflect the lesson status. 4. Stage all related changes atomically: ```bash git add phases/12-multimodal-ai/03-example-lesson README.md ROADMAP.md ``` 5. Commit using the conventional format: ```bash git commit -m "feat(phase-12/03): add example-lesson" ``` 6. Push and create a pull request: ```bash git push -u origin my-feature-branch gh pr create --title "feat(phase-12/03): add example-lesson" \ --body "Adds the Example Lesson covering …" ``` ## Summary - **One commit per lesson**: Each lesson directory requires its own commit to maintain granular history. - **Conventional format**: Use `feat(phase-NN/MM): ` with ≤72 character titles and explanatory bodies. - **Atomic staging**: Always add the lesson directory, [`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) in a single `git add` command. - **Documentation location**: All rules are defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the **Hard rules** and **New-lesson onboarding** sections. ## Frequently Asked Questions ### What happens if I combine multiple lessons into one commit? Your pull request will violate the **Hard rules** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), forcing maintainers to request changes. This policy ensures that individual lessons can be reverted independently without affecting the curriculum's integrity. ### Why must I update README.md and ROADMAP.md in the same commit? The atomic commit workflow keeps the three canonical locations—the lesson source, the public index in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), and the status tracker in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)—synchronized. This prevents scenarios where a lesson exists in the codebase but remains undocumented or mislabeled in the project roadmap. ### Can I use commit types other than "feat" for lesson contributions? The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification focuses on the `feat(phase-NN/MM)` pattern for new lessons. While other conventional commit types like `fix` or `docs` might apply to corrections, new lesson additions must follow the `feat` prefix to maintain consistency with automated tooling and changelog generation. ### Where do I find the exact commit message format? The precise format is documented in the **Hard rules** section of [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at the repository root. It specifies the 72-character title limit, the `feat(phase-NN/MM): ` structure, and the requirement to explain the *why* rather than the *what* in the commit body.