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

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).

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 validator scans only files touched by a commit. If you bundle multiple lessons, the audit cannot reliably attribute failures, and the README.md auto-sync step that rewrites lesson counts could mis-calculate rows. One commit per lesson guarantees the site builder (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.

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 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 – 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 – 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 linking to the new lesson: [Lesson Title](phases/NN-phase-slug/MM-lesson-slug/)
• Update 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.

python3 scripts/audit_lessons.py
python3 scripts/check_readme_counts.py

Then test the actual code:

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

The audit_lessons.py script validates header comments, test counts, folder layout, and schema compliance. The 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:

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.

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:

# 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 rule 1 to maintain automation stability.
• Each lesson must include docs/en.md, code/main.<lang>, code/tests/, and quiz.json in the phases/NN-phase-slug/MM-lesson-slug/ directory.
• Always update README.md and ROADMAP.md in the same commit as the lesson.
• Run 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 tool scans only touched files and cannot attribute failures to specific lessons when multiple are bundled. Additionally, the 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 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 counts during the readme-counts-sync job. However, you must manually add the lesson link row to README.md and update 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}