# How Conventional Commit Format Works in the AI-Engineering-From-Scratch Repository

> Understand the strict conventional commit format in rohitg00/ai-engineering-from-scratch. Learn how feat, phase-NN/MM scope, and kebab-case descriptions ensure readability and machine processing.

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

---

**The `rohitg00/ai-engineering-from-scratch` repository enforces a strict conventional commit format defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) that combines a mandatory `feat` prefix, a `phase-NN/MM` scope, and a kebab-case description to keep the curriculum readable and machine-processable.**

According to the `rohitg00/ai-engineering-from-scratch` source code, every contribution must follow the exact conventional commit style spelled out in the repository's contribution manual. This standardized format allows CI scripts and the site builder to automatically map each pull request to the correct lesson directory without manual intervention.

## The Conventional Commit Format Specification

The rule is formally defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 40-42) and breaks every commit subject into three distinct parts.

### Subject Length Limit

The commit header must be **72 characters or fewer**. This hard limit guarantees that subjects render cleanly in GitHub, terminal log viewers, and notification emails without truncation.

### Required Prefix and Scope Syntax

Every commit must use the **`feat`** prefix. Unlike broader conventional commit specifications that allow `fix`, `docs`, or `chore`, this curriculum treats all new and updated lessons as features.

Immediately after the prefix, the scope uses the exact syntax `feat(phase-NN/MM)` where:

- `NN` is the two-digit phase number (for example, `01`, `02`).
- `MM` is the two-digit lesson number within that phase.
- The scope is wrapped in parentheses and directly follows the prefix.

### Slug Description Format

After the colon and a single space, the description contains a short **kebab-case slug** that uniquely identifies the lesson. This slug normally matches the target directory name and contains only lowercase letters and hyphens.

A valid subject line looks like this:

```text
feat(phase-03/05): add-tokenizer-implementation

```

## Automation That Relies on Conventional Commits

The repository's tooling parses commit subjects to enforce repository hygiene and generate documentation.

### PR Lesson Auditing

The **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** script reads the commit scope to verify that a pull request modifies exactly one lesson directory. If the commit subject claims `feat(phase-02/07)`, the script expects file changes only inside the corresponding phase and lesson path.

### README Count Synchronization

Similarly, **[`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)** uses the commit subject to validate that lesson counts in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) stay in sync with actual repository content. By extracting the phase and lesson numbers from the conventional commit header, the script confirms that the markdown table listing lessons reflects the latest additions.

### Site Builder Link Generation

The **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** script relies on the phase and lesson numbers embedded in commit subjects to map pull requests to their documentation entries. Because the conventional commit already contains the `phase-NN/MM` identifier, the builder can reliably locate the lesson title from the markdown link in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and generate the correct site navigation.

## Practical Conventional Commit Examples

The following examples demonstrate valid subjects for different types of curriculum changes.

### Adding a New Lesson

When creating a new lesson in Phase 02, Lesson 07, the commit subject is:

```text
feat(phase-02/07): add-gradient-descent-demo

```

### Updating an Existing Lesson

For improvements to an existing lesson in Phase 04, Lesson 03, use:

```text
feat(phase-04/03): improve-attention-visualisation

```

### Full Commit Message Body

A complete commit message includes the conventional subject followed by a detailed body:

```text
feat(phase-01/01): add-linear-regression-lesson

Implemented a simple OLS regression in Python. Added unit tests
(5+ passing) and updated the lesson's README entry. No API keys
or external dependencies were introduced.

```

## Summary

- The conventional commit format in `rohitg00/ai-engineering-from-scratch` is strictly defined in **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** and requires a **`feat`** prefix.
- The scope must follow the exact pattern **`phase-NN/MM`** to identify the target lesson.
- The description uses a **kebab-case slug** that typically matches the lesson directory name.
- **Automation scripts**—including [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py), and [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)—parse these commits to audit PRs, validate [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), and build the documentation site.

## Frequently Asked Questions

### What happens if I use a prefix other than `feat` in this repository?

The contribution manual in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) mandates the **`feat`** prefix for all lesson changes. Other prefixes such as `fix`, `docs`, or `chore` are not used in this curriculum, and commits using them may fail automated checks or be rejected during review.

### How does the `phase-NN/MM` scope help automate repository maintenance?

The scope gives **machine-readable coordinates** for every change. Tools like [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) extract the phase and lesson numbers to verify that a PR touches only one directory and that [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) counts remain accurate.

### Can the commit subject exceed 72 characters?

No. The repository imposes a **72-character limit** on the subject line. This ensures clean rendering across GitHub interfaces, email clients, and terminal logs, and longer subjects may violate the project's hard rules.

### Where is the conventional commit rule formally documented?

The rule is formally defined in **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** at lines 40-42. This file serves as the contribution manual and lists all formatting requirements alongside other hard rules for contributors.