Contributing to AI Engineering From Scratch: Guidelines and Commit Format

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

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:

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, 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 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 and ROADMAP.md remain parsable and that the generated 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 parses README.md, ROADMAP.md, and glossary/terms.md to generate 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 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 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 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 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:

# 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 and ROADMAP.md tables remain well-formed. If the builder reports parsing errors, adjust the markdown tables according to the patterns described in 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 and ROADMAP.md parse correctly and only generate timestamp changes in site/data.js.
• No code comments: Place all explanatory text in 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 before committing?

The site/build.js script parses README.md, ROADMAP.md, and glossary/terms.md to generate the website's data file (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 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 file within the specific lesson directory (e.g., 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.

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