# How to Contribute a New AI Lesson to ai-engineering-from-scratch: Commit Conventions & Structure > Learn to contribute to ai-engineering-from-scratch by following commit conventions and structural guidelines. Add your new AI lesson easily and effectively. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: how-to-guide - Published: 2026-06-20 --- **To contribute a new AI lesson to the ai-engineering-from-scratch curriculum, create a standardized lesson skeleton under `phases/XX-phase-slug/NN-lesson-slug/`, follow the commit convention `feat(phase-NN/MM): add `, and update both [`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) to maintain repository integrity.** Contributing to the **ai-engineering-from-scratch** repository requires strict adherence to architectural conventions defined 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). Each lesson must live as an isolated commit with a specific conventional format, ensuring the automated CI pipelines and curriculum indexes remain synchronized. ## Lesson Structure Requirements Every new AI lesson must reside in a dedicated directory following the pattern `phases/XX-phase-slug/NN-lesson-slug/`. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 15-24, this directory must contain four standard sub-folders: - `docs/` – Documentation files - `code/` – Implementation files - `outputs/` – Optional generated artifacts - `tests/` – Unit tests (typically nested as `code/tests/`) The required files include [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for the lesson guide, at least one runnable implementation in `code/main.`, a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file, and unit tests in `code/tests/`. ### Creating the Directory Skeleton Use the following bash command to generate the proper structure: ```bash mkdir -p phases/03-transformers-deep-dive/12-new-lesson/{docs,code,code/tests,outputs} ``` ## Documentation Standards The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must begin with standardized front-matter as defined in the *Lesson contract* within [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 65-78. This includes: - **Title** and **hook** (one-line summary) - **Type** (e.g., Build, Theory) - **Languages** supported (Python, TypeScript, Rust, or Julia) - **Prerequisites** (previous lesson numbers) - **Time estimate** - **Learning objectives** Follow the markdown layout specifications shown in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 40-72 for consistency across the curriculum. Example front-matter: ```markdown # My New Lesson > One‑line hook that captures the core idea. **Type:** Build **Languages:** Python **Prerequisites:** 07‑self‑attention-from‑scratch **Time:** ~30 minutes ## Learning Objectives - Explain the concept … - Implement the algorithm … - Compare with a library implementation … ``` ## Code Implementation Requirements Place your main implementation in `code/main.` using Python, TypeScript, Rust, or Julia. As specified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 2-6 and 62-66, prepend a 4-6 line header comment that cites the lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) path and any RFC or paper sources. ### Unit Testing Standards Create at least five unit tests in `code/tests/` that can be executed with the language's standard test runner. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 8-12, verify functionality with: ```bash python3 -m unittest discover ``` ## Quiz Configuration Every lesson must include a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file adhering to the exact six-question schema defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 83-99: one pre-assessment question, three check-in questions, and two post-assessment questions. ## Repository Index Updates Before committing, update the public indexes to ensure the automated site generator ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) can parse your contribution. ### README.md Requirements Add a new row to the lesson table using the Markdown link format. The parser extracts the URL from this link syntax, as documented in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 7-18 and [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 53-57: ```markdown | 12 | [My New Lesson](phases/03-transformers-deep-dive/12-new-lesson/) | Build | Python | ``` ### ROADMAP.md Updates Add a status glyph to your lesson's row: `✅` for finished, `🚧` for work-in-progress, or `⬚` for planned. This convention appears in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 19-20. ## Commit Conventions The ai-engineering-from-scratch repository enforces a strict "one-commit-per-lesson" rule. Each lesson introduction must use a conventional subject line limited to 72 characters: ``` feat(phase-NN/MM): add ``` According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 40-42, the commit body should explain **why** the lesson is added (its educational value), not **what** files contain. For example: ```bash git add phases/03-transformers-deep-dive/12-new-lesson git commit -m "feat(phase-03/12): add my-new-lesson" ``` This format triggers CI automation that rebuilds [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and verifies README counts. ## Validation and Submission Before pushing, execute the audit scripts and lesson-specific tests to ensure everything runs and the README/ROADMAP syntax remains parsable, as required by [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 15-18. Once validated, push your branch and create a pull request with the same title as your commit subject. The CI pipeline automatically validates the commit message format and checks that the lesson skeleton meets all structural requirements. ## Summary - **Structure**: Create lessons under `phases/XX-phase-slug/NN-lesson-slug/` with `docs/`, `code/`, `code/tests/`, and optional `outputs/` directories - **Documentation**: Include standardized front-matter in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with title, hook, type, languages, prerequisites, time estimate, and learning objectives - **Code**: Implement in `code/main.` with 4-6 line header comments citing sources, plus at least five unit tests - **Quiz**: Provide [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with the six-question schema (1 pre, 3 check, 2 post) - **Indexes**: Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) with Markdown link format and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) with status glyphs (`✅`, `🚧`) - **Commits**: Use `feat(phase-NN/MM): add ` format with 72-character limit and explanatory body - **Validation**: Run local audit scripts and tests before submitting PR ## Frequently Asked Questions ### How do I determine the correct phase and lesson numbers for my contribution? Check [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to identify the current phase structure and the next available lesson number in your target phase. The numbering scheme follows `NN` format (e.g., `12`) within each phase directory named `XX-phase-slug` (e.g., `03-transformers-deep-dive`). Ensure your lesson number follows sequentially from existing lessons in that phase. ### What programming languages are supported for lesson implementations? The repository accepts implementations in **Python**, **TypeScript**, **Rust**, and **Julia**. Place your main code in `code/main.` with the appropriate extension. The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) and documentation should specify which languages are supported for that particular lesson. ### Why does my commit need to be exactly one commit per lesson? The repository maintains a strict "one-commit-per-lesson" rule to preserve curriculum integrity and enable atomic rollbacks. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), this convention ensures that automated CI pipelines can correctly regenerate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and maintain the lesson index. If you need to make changes after initial submission, amend your commit or create a new single commit for the lesson update. ### What happens if I don't update README.md and ROADMAP.md? The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script generates the public curriculum site by parsing [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) for lesson links and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) for status tracking. Without these updates, your lesson will not appear in the public index or navigation, and CI checks will fail. The Markdown link format `[Lesson Title](path)` is specifically required for the parser to extract URLs correctly.