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

> Learn how to contribute to the ai-engineering-from-scratch project. Fork the repo, add content, and submit a pull request. Start your AI engineering journey today.

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

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/03-deep-learning-core/15-gradient-descent/code/main.py):

```python

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) that links to the lesson folder:

```markdown
| 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/zh.md)) while keeping the original [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) intact. The site generator ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/requirements.txt); TypeScript via [`package.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/package.json))
- **Site Generation**: Confirm that [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) rebuilds [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md)

## Key Files for Contributors

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

- **[`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md)**: Contains detailed contribution guidelines, file-structure rules, and CI expectations
- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)**: Houses the main curriculum overview and lesson tables that must stay synchronized with new content
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Generates the static site data ([`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)) from [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md)
- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)
- **Submit exactly one lesson per PR** to maintain review quality and repository organization
- **Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) table entry to include the new language. The [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js). If checks fail, review the error logs from [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/requirements.txt).

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

Yes. Each [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.