# How to Contribute to the AI Curriculum Following the One-Commit-Per-Lesson Rule

> Learn to contribute to the AI curriculum with one commit per lesson. Package lessons atomically including code, docs, and tests in this guide for rohitg00/ai-engineering-from-scratch.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-24

---

**To contribute to the rohitg00/ai-engineering-from-scratch curriculum, you must package each lesson as a single atomic commit that includes the lesson directory, documentation, code, tests, and updated index files.**

The rohitg00/ai-engineering-from-scratch repository is structured as a progressive curriculum rather than a monolithic application. Each lesson resides in its own directory under `phases/` and functions as an independent artifact with its own documentation, runnable code, tests, and quiz. Because the CI pipeline and website generator rely on atomic updates, the project enforces a strict **one-commit-per-lesson** policy defined in [[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).

## Why the One-Commit-Per-Lesson Rule Exists

This policy ensures three critical outcomes for the curriculum's quality and automation.

**Review granularity** – By isolating changes to a single lesson, reviewers can focus exclusively on the pedagogical accuracy and code quality of that specific unit without noise from other modifications.

**Accurate contribution attribution** – The automation tracks which commits touch which lesson directories. Atomic commits enable precise contribution counts per lesson, giving maintainers clear visibility into who built what.

**Stable automation** – The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validator scans only files touched by a commit. If you bundle multiple lessons, the audit cannot reliably attribute failures, and the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) auto-sync step that rewrites lesson counts could mis-calculate rows. One commit per lesson guarantees the site builder ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) can safely regenerate the curriculum site without manual intervention.

## Step-by-Step Contribution Workflow

Follow this exact sequence to ensure your PR passes the automated checks.

### Fork and Branch Setup

Start by forking the repository and creating a feature branch named specifically for the lesson you will add.

```bash
git clone https://github.com/your-username/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
git checkout -b add-lesson-phase03-gradient-descent

```

### Scaffold the Lesson Structure

Create the lesson directory following the strict layout: `phases/NN-phase-slug/MM-lesson-slug/`. You can generate this scaffold manually or use the helper script.

```bash
bash scripts/scaffold-lesson.sh 03-gradient-descent

```

This creates the required folder hierarchy under `phases/03-math/01-gradient-descent/`.

### Populate Required Files

Every lesson must contain four specific components:

1. **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** – The lesson narrative with front-matter (title, type, languages, prerequisites, estimated time).
2. **`code/main.<lang>`** – A runnable implementation following the "build-it-first, use-it-second" pedagogical approach.
3. **`code/tests/`** – At least five unit tests runnable via the language's standard test runner.
4. **[`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)** – Exactly six questions following the schema (1 pre-assessment, 3 checkpoint, 2 post-assessment).

Additionally, you must update the index files:
- Add a row to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) linking to the new lesson: `[Lesson Title](phases/NN-phase-slug/MM-lesson-slug/)`
- Update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) with status glyphs (✅ for complete, 🚧 for in-progress)

### Validate Locally

Before committing, run the audit scripts to verify your lesson meets the contract requirements.

```bash
python3 scripts/audit_lessons.py
python3 scripts/check_readme_counts.py

```

Then test the actual code:

```bash
cd phases/03-math/01-gradient-descent/code
python3 main.py && python3 -m unittest discover tests -v

```

The [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) script validates header comments, test counts, folder layout, and schema compliance. The [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py) script verifies the README lesson counts are accurate (though the CI will auto-fix this on merge).

### Commit Using the Conventional Format

**Create exactly one commit** that adds the entire lesson directory and updates the top-level index files. The commit message must follow the conventional format:

```bash
git add phases/03-math/01-gradient-descent README.md ROADMAP.md
git commit -m "feat(phase-03/01): add gradient descent lesson"

```

Message format: `feat(phase-NN/MM): add <lesson-slug>`

### Push and Open a Pull Request

Push your branch and create a PR using the GitHub CLI or web interface.

```bash
git push origin add-lesson-phase03-gradient-descent
gh pr create --title "feat(phase-03/01): add gradient descent lesson" \
             --body "Introduces gradient descent from first principles."

```

The PR will trigger three CI jobs: `audit`, `readme-counts-sync`, and `site-rebuild`. All must pass before merge.

## Complete Contribution Example

Here is the full workflow from fork to PR:

```bash

# 1. Fork & clone

git clone https://github.com/your-username/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch

# 2. Create a branch for the new lesson

git checkout -b add-lesson-phase03-gradient-descent

# 3. Scaffold the lesson (optional helper)

bash scripts/scaffold-lesson.sh 03-gradient-descent

# 4. Edit the files (docs/en.md, code/main.py, quiz.json, etc.)

# 5. Run local checks

python3 scripts/audit_lessons.py
python3 scripts/check_readme_counts.py
cd phases/03-math/01-gradient-descent/code
python3 main.py && python3 -m unittest discover tests -v

# 6. Commit – one commit only

git add phases/03-math/01-gradient-descent README.md ROADMAP.md
git commit -m "feat(phase-03/01): add gradient descent lesson"

# 7. Push & open PR

git push origin add-lesson-phase03-gradient-descent
gh pr create --title "feat(phase-03/01): add gradient descent lesson" \
             --body "Introduces gradient descent from first principles."

```

## Summary

- **One commit per lesson** is mandatory per [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) rule 1 to maintain automation stability.
- Each lesson must include [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/main.<lang>`, `code/tests/`, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) in the `phases/NN-phase-slug/MM-lesson-slug/` directory.
- Always update [`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 the same commit as the lesson.
- Run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) locally to validate structure before pushing.
- Use the conventional commit format: `feat(phase-NN/MM): add <lesson-slug>`.

## Frequently Asked Questions

### What happens if I commit multiple lessons in one PR?

The CI pipeline will fail. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) tool scans only touched files and cannot attribute failures to specific lessons when multiple are bundled. Additionally, the [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py) auto-sync may miscount rows, requiring manual intervention from maintainers.

### Can I fix a typo in a lesson without following the one-commit rule?

No. Any modification to a lesson—including typo fixes—must follow the atomic commit policy. This ensures the [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator and contribution trackers maintain accurate attribution. Small fixes should still be single commits touching only that lesson's directory.

### Do I need to manually update the README lesson counts?

No. While you should run `python3 scripts/check_readme_counts.py` locally to verify, the CI pipeline automatically updates [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) counts during the `readme-counts-sync` job. However, you must manually add the lesson link row to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status glyphs before committing.

### What is the correct conventional commit format for lesson contributions?

Use `feat(phase-NN/MM): add <lesson-slug>` where `NN` is the phase number, `MM` is the lesson number, and `<lesson-slug>` is the hyphenated lesson name. For example: `feat(phase-03/01): add gradient-descent`.