# Contributing to AI Engineering From Scratch: Guidelines and Commit Format

> Learn contributing guidelines for AI Engineering From Scratch. Follow our strict commit format feat(phase-NN/MM): <slug> for curriculum integrity and automated synchronization.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: getting-started
- Published: 2026-09-01

---

**The AI Engineering From Scratch repository requires a strict one-lesson-per-commit workflow with conventional commit messages formatted as `feat(phase-NN/MM): <slug>` to ensure curriculum integrity and automated site synchronization.**

The *AI Engineering From Scratch* repository maintains a rigorous, lesson-centric contribution workflow designed to keep the educational curriculum coherent and the generated website synchronized. Understanding the contributing guidelines is essential for anyone looking to add lessons or fix content in this open-source AI curriculum. According to the repository's canonical documentation in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md), contributors must follow specific formatting rules, commit conventions, and validation steps that differ from standard open-source practices.

## One-Lesson-Per-Commit Policy

Every pull request must contain **exactly one change per lesson directory**. This rule ensures that each lesson can be reviewed, tracked, and credited independently without cross-contamination of unrelated curriculum content. As implemented in `rohitg00/ai-engineering-from-scratch`, this policy prevents merge conflicts in the structured phase-based directory hierarchy and maintains the linear progression of the AI engineering curriculum. Violating this rule—such as modifying lessons from different phases in a single commit—will result in PR rejection according to the hard rules defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).

## Conventional Commit Format

All commits must follow a strict conventional commit pattern that the automated systems parse to generate the website's lesson index.

### Commit Message Structure

Commit titles must be **≤ 72 characters** and use the exact pattern:

```

feat(phase‑NN/MM): <slug>

```

- **`<phase‑NN>`**: The two-digit phase number (e.g., `phase‑03`)
- **`<MM>`**: The two-digit lesson number within that phase (e.g., `05`)
- **`<slug>`**: The kebab-case identifier of the lesson (e.g., `gradient‑descent`)

For example, adding the fifth lesson in phase three about gradient descent requires the commit message:

```bash
feat(phase-03/05): gradient-descent

```

### Commit Body Requirements

The body of the commit message must **explain why the change is made**, not what the change does. This requirement ensures that the git history captures the pedagogical reasoning behind curriculum modifications rather than redundant descriptions of file edits. As specified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), the separation of concerns between commit subject (what) and body (why) helps maintainers understand the educational intent behind structural changes.

## Pull Request Workflow

Contributors must follow this exact sequence, as documented in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 45-52:

1. **Fork the repository**: `gh repo fork rohitg00/ai-engineering-from-scratch` creates a personal copy you can push to.

2. **Create a feature branch**: `git checkout -b add‑lesson‑phase03‑gradient‑descent` — the branch name should reflect the specific lesson you are adding.

3. **Make the change**: Edit files under the appropriate lesson directory (e.g., `phases/03‑phase‑slug/05‑gradient‑descent/...`) following the lesson contract requirements: docs, code, tests, and quiz components.

4. **Run the site builder**: `node site/build.js` verifies that [`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) remain parsable and that the generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) only shows timestamp changes.

5. **Commit with proper format**: `git add . && git commit -m "feat(phase-03/05): gradient-descent"` uses the required commit format.

6. **Push to your fork**: `git push origin add‑lesson‑phase03‑gradient‑descent` sends your branch to your personal repository.

7. **Open a pull request**: `gh pr create --title "feat(phase-03/05): gradient-descent" --body "Add lesson on gradient descent with implementation, tests, and quiz."` — the PR description should outline the *why* of the contribution, not merely list the files changed.

## Maintaining Website Consistency

The file [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) parses [`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) to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). After any edit to those structural files, you must run the builder locally and verify that the only change in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) is a timestamp update. This guarantees that lesson tables and phase headers stay in the exact format expected by the static site generator. According to [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 7-24, failing to run this validation step before submitting a PR will break the website's automated generation pipeline.

## Coding Style Standards

The repository enforces specific content formatting rules distinct from typical Python or JavaScript projects:

- **No comments inside code files** — all explanations belong in the accompanying [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file within the lesson directory.
- **Use language-appropriate fenced code block tags** (e.g., `python`, `typescript`, `javascript`) in documentation files.
- **Align language choices with the lesson's "Languages" front-matter** to ensure consistency between the implemented code and the documented prerequisites.

These style rules are codified as **hard rules** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) points 3-4 and are enforced during PR review.

## Complete Contribution Example

Here is a minimal, runnable example of contributing a new lesson called "gradient-descent" in Phase 3, Lesson 05:

```bash

# 1️⃣ Fork & clone (once)

gh repo fork rohitg00/ai-engineering-from-scratch
git clone https://github.com/<your-username>/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch

# 2️⃣ Create a feature branch

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

# 3️⃣ Add lesson files following the directory contract

mkdir -p phases/03-phase-learning/05-gradient-descent/{code,docs,tests,outputs}
echo "# Gradient Descent" > phases/03-phase-learning/05-gradient-descent/docs/en.md

echo -e "def main():\n    pass" > phases/03-phase-learning/05-gradient-descent/code/main.py
echo -e "import unittest\nclass TestMain(unittest.TestCase):\n    def test_dummy(self):\n        self.assertTrue(True)" > phases/03-phase-learning/05-gradient-descent/tests/test_main.py

# 4️⃣ Verify site generation (critical step)

node site/build.js   # Should succeed with only a timestamp change in site/data.js

# 5️⃣ Stage & commit with proper format

git add .
git commit -m "feat(phase-03/05): gradient-descent"

# 6️⃣ Push & open PR

git push origin add-lesson-phase03-05-gradient-descent
gh pr create --title "feat(phase-03/05): gradient-descent" \
  --body "Add a new lesson on gradient descent, including implementation, tests, and quiz."

```

Running `node site/build.js` after editing confirms that the [`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) tables remain well-formed. If the builder reports parsing errors, adjust the markdown tables according to the patterns described in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md).

## Summary

- **One-lesson-per-commit**: Each PR must modify exactly one lesson directory to ensure independent review and tracking.
- **Strict commit format**: Use `feat(phase-NN/MM): <slug>` with a maximum of 72 characters in the subject line.
- **Explain reasoning**: Commit bodies must describe why the change improves the curriculum, not what files were modified.
- **Validate locally**: Always run `node site/build.js` to verify that [`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) parse correctly and only generate timestamp changes in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js).
- **No code comments**: Place all explanatory text in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) within the lesson directory, keeping source files clean.

## Frequently Asked Questions

### What is the exact commit message format for AI Engineering From Scratch?

The required format is `feat(phase-NN/MM): <slug>` where NN is the two-digit phase number, MM is the two-digit lesson number, and slug is the kebab-case lesson identifier. For example: `feat(phase-03/05): gradient-descent`. The subject must not exceed 72 characters.

### Why does the repository require running [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) before committing?

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses [`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) to generate the website's data file ([`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)). Running this locally ensures your edits do not break the static site generator's parsing logic and verifies that structural changes produce only expected timestamp updates.

### Can I submit multiple lessons in a single pull request?

No. The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) hard rules explicitly forbid this. Each pull request must contain exactly one change per lesson directory. This policy maintains curriculum coherence and allows individual lessons to be reviewed, credited, and reverted independently without affecting unrelated content.

### Where should I place code comments if not in the source files?

All explanatory text belongs in the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file within the specific lesson directory (e.g., [`phases/03-phase-learning/05-gradient-descent/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/03-phase-learning/05-gradient-descent/docs/en.md)). Source code files in the `code/` directory must remain comment-free to enforce a clean separation between implementation and pedagogy.