How to Contribute to AI Engineering from Scratch: A Complete Guide

You can contribute to the ai-engineering-from-scratch curriculum by forking the repository, creating a feature branch, adding content following the lesson structure in phases/<phase-slug>/<lesson-slug>/, and submitting a pull request that passes the automated CI pipeline.

The ai-engineering-from-scratch project is an open-source curriculum maintained by rohitg00 that teaches AI engineering by building every component from the ground up. Whether you want to add new lessons, fix bugs, improve documentation, or provide translations, the repository welcomes contributions through a structured workflow defined in CONTRIBUTING.md.

Contribution Workflow Overview

The contribution process for ai-engineering-from-scratch follows these specific steps:

1. Fork the repository at https://github.com/rohitg00/ai-engineering-from-scratch/fork
2. Create a feature branch using a descriptive name (e.g., git checkout -b add-lesson-phase-3-gradient-descent)
3. Add or modify content following the conventions in CONTRIBUTING.md
4. Run local tests with python -m unittest discover in the lesson's code/ folder to ensure all implementations execute correctly
5. Update top-level index files including README.md, ROADMAP.md, and the glossary/ directory so the website generator can locate your changes
6. Open a pull request with a clear description; the CI pipeline will automatically lint, audit, and rebuild the site data

Lesson Structure and Organization

The curriculum is organized into 20 phases and approximately 500 lessons. Each lesson lives in its own directory under phases/<phase-slug>/<lesson-slug>/ and contains:

<lesson-slug>/
├── code/           # runnable implementations (Python, TypeScript, Rust, Julia)

├── docs/
│   └── en.md       # lesson narrative (required)

└── outputs/        # optional prompts, skills, agents, or MCP servers

How to Add a New Lesson

When contributing a new lesson to ai-engineering-from-scratch, you must complete these required components:

Write the Lesson Documentation

Create docs/en.md using the front-matter template that includes the title, hook, type, languages, prerequisites, and learning objectives.

Provide Runnable Code

Include at least one implementation in the code/ directory. For example, a gradient descent implementation belongs in phases/03-deep-learning-core/15-gradient-descent/code/main.py:

# phases/03-deep-learning-core/15-gradient-descent/code/main.py

"""
Lesson 15 – Gradient Descent
Build: implement gradient descent from scratch.
Use: compare against PyTorch's optimizer.
"""

import numpy as np

def gradient_descent(f, grad_f, x0, lr=0.1, steps=100):
    x = x0
    for _ in range(steps):
        x = x - lr * grad_f(x)
    return x

# Example: minimize f(x) = (x-3)^2

f = lambda x: (x - 3) ** 2
grad_f = lambda x: 2 * (x - 3)
optimum = gradient_descent(f, grad_f, x0=0.0)
print(f"Optimum: {optimum:.2f}")   # → 2.99 (≈3)

Create Assessment Materials

Add a quiz.json file containing six questions: one pre-assessment, three "check your understanding" questions, and two post-assessment questions.

Update Curriculum Indexes

Add a row to the lesson table in README.md that links to the lesson folder:

| 15 | [Gradient Descent](phases/03-deep-learning-core/15-gradient-descent/) | Build | Python |

Follow the Hard Rule

Commit exactly one lesson per PR—this is a strict repository requirement that maintainers enforce.

Translating Existing Content

To translate a lesson when contributing to ai-engineering-from-scratch, add a new markdown file under docs/ (e.g., zh.md) while keeping the original en.md intact. The site generator (site/build.js) automatically processes translations during the build phase.

Testing and CI Validation

Before submitting your contribution, verify your changes against the automated pipeline:

• Lesson Integrity: The CI runs scripts/audit_lessons.py to validate file naming conventions and required outputs
• Code Execution: All code must run with declared dependencies (Python via requirements.txt; TypeScript via package.json)
• Site Generation: Confirm that site/build.js rebuilds site/data.js cleanly without errors
• Markdown Patterns: Verify that lesson tables and phase headers retain the required patterns specified in lines 13-16 of CONTRIBUTING.md

Key Files for Contributors

Understanding these core files helps you navigate the ai-engineering-from-scratch codebase effectively:

• CONTRIBUTING.md: Contains detailed contribution guidelines, file-structure rules, and CI expectations
• README.md: Houses the main curriculum overview and lesson tables that must stay synchronized with new content
• site/build.js: Generates the static site data (site/data.js) from README.md, ROADMAP.md, and glossary/terms.md
• scripts/audit_lessons.py: The CI script that checks lesson integrity, file naming, and required tests

Summary

• Fork and branch from the main repository before making changes to contribute to ai-engineering-from-scratch
• Follow the lesson structure: phases/<phase-slug>/<lesson-slug>/ with code/, docs/en.md, and quiz.json
• Submit exactly one lesson per PR to maintain review quality and repository organization
• Update README.md with new lesson entries in the proper table format so the site generator can index them
• Run local tests using python -m unittest discover in the lesson's code/ folder before committing
• Respect translation protocols by adding new language files alongside (not replacing) the original en.md

Frequently Asked Questions

How do I report a bug in an existing lesson?

Open an issue describing the error, or submit a PR directly fixing the bug in the relevant lesson directory under phases/<phase-slug>/<lesson-slug>/. Ensure you run python -m unittest discover in the lesson's code/ folder to verify your fix doesn't break existing functionality, as required by the CI pipeline.

Can I contribute a lesson in a programming language not currently listed?

Yes. The curriculum supports Python, TypeScript, Rust, and Julia. Add your implementation in the lesson's code/ directory with the appropriate file extension and update the README.md table entry to include the new language. The audit_lessons.py script will verify the code executes with your declared dependencies.

What happens if my PR fails the CI checks?

The CI pipeline validates lesson table patterns, executes code against declared dependencies, and rebuilds the site data via site/build.js. If checks fail, review the error logs from scripts/audit_lessons.py or the build output, fix the issues, and push updates to your branch. Common failures include malformed markdown tables or code that doesn't run with the provided requirements.txt.

Is there a specific format for the quiz.json file?

Yes. Each quiz.json must contain exactly six questions: one pre-assessment question, three "check your understanding" questions, and two post-assessment questions. Refer to existing lessons in the phases/ directory for the exact JSON schema and question format required by the curriculum standards.

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