Commit Rules for Contributing to AI Engineering from Scratch

The repository enforces three strict commit rules defined in AGENTS.md: one commit per lesson directory, conventional commit subjects following the feat(phase-NN/MM): <slug> pattern, and an atomic workflow that stages lesson files alongside README.md and ROADMAP.md updates.

Contributors to the rohitg00/ai-engineering-from-scratch curriculum must follow specific commit rules to maintain a clean, auditable history. These guidelines, documented in the Hard rules section of AGENTS.md, ensure that every lesson can be tracked, reviewed, and rolled back independently without affecting the broader codebase.

Where Commit Rules Are Documented

The authoritative source for all commit policies resides in AGENTS.md at the repository root. This file contains the Hard rules section that mandates the one-commit-per-lesson requirement and the New-lesson onboarding section that details the exact git add and git commit commands required for contributions.

The Three Core Commit Rules

One Commit Per Lesson Directory

Each pull request must contain a separate commit for every lesson added or modified. If a PR introduces ten lessons, it must include ten distinct commits. This granularity guarantees fine-grained history and enables maintainers to roll back a single lesson without cascading effects on unrelated content.

Conventional Commit Subjects

Commit titles must follow the pattern feat(phase-NN/MM): <slug> and remain under 72 characters. The commit body must describe why the change is made rather than what the code does. This convention supports automated tooling like changelog generators and provides reviewers with immediate contextual understanding.

Atomic Commit Workflow

Contributors must stage the lesson directory, README.md, and ROADMAP.md in a single git add command before committing. This atomic approach ensures that the three required source locations—the lesson files, the public index, and the roadmap status—remain perfectly synchronized in the repository history.

Practical Contribution Workflow

When adding a new lesson, follow this exact sequence defined in the New-lesson onboarding section:

1. Create the lesson folder structure:

mkdir -p phases/12-multimodal-ai/03-example-lesson/{docs,code,tests,outputs}

2. Write the lesson content, including documentation, code, and tests.

3. Update README.md with a new row in the lessons table and modify ROADMAP.md to reflect the lesson status.

4. Stage all related changes atomically:

git add phases/12-multimodal-ai/03-example-lesson README.md ROADMAP.md

5. Commit using the conventional format:

git commit -m "feat(phase-12/03): add example-lesson"

6. Push and create a pull request:

git push -u origin my-feature-branch
gh pr create --title "feat(phase-12/03): add example-lesson" \
    --body "Adds the Example Lesson covering …"

Summary

• One commit per lesson: Each lesson directory requires its own commit to maintain granular history.
• Conventional format: Use feat(phase-NN/MM): <slug> with ≤72 character titles and explanatory bodies.
• Atomic staging: Always add the lesson directory, README.md, and ROADMAP.md in a single git add command.
• Documentation location: All rules are defined in AGENTS.md under the Hard rules and New-lesson onboarding sections.

Frequently Asked Questions

What happens if I combine multiple lessons into one commit?

Your pull request will violate the Hard rules in AGENTS.md, forcing maintainers to request changes. This policy ensures that individual lessons can be reverted independently without affecting the curriculum's integrity.

Why must I update README.md and ROADMAP.md in the same commit?

The atomic commit workflow keeps the three canonical locations—the lesson source, the public index in README.md, and the status tracker in ROADMAP.md—synchronized. This prevents scenarios where a lesson exists in the codebase but remains undocumented or mislabeled in the project roadmap.

Can I use commit types other than "feat" for lesson contributions?

The AGENTS.md specification focuses on the feat(phase-NN/MM) pattern for new lessons. While other conventional commit types like fix or docs might apply to corrections, new lesson additions must follow the feat prefix to maintain consistency with automated tooling and changelog generation.

Where do I find the exact commit message format?

The precise format is documented in the Hard rules section of AGENTS.md at the repository root. It specifies the 72-character title limit, the feat(phase-NN/MM): <slug> structure, and the requirement to explain the why rather than the what in the commit body.

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