How to Resolve Merge Conflicts in the AI Engineering from Scratch Repository

To resolve merge conflicts in the AI Engineering from Scratch repository, fetch the latest main branch, reconcile conflicts in lesson directories and metadata files while keeping each lesson limited to one atomic commit, run the validation scripts to sync badge counts, and push to let CI rebuild the site catalog.

The rohitg00/ai-engineering-from-scratch repo is structured as a curriculum where each lesson is isolated in its own folder and tracked by exactly one dedicated commit. Because lesson paths, README.md link rows, ROADMAP.md status tables, and the generated site/data.js catalog are tightly coupled, pull requests frequently overlap in the same files. The repository documents the official resolution process in AGENTS.md, and the steps below align with that source to keep the curriculum intact.

Where Merge Conflicts Typically Appear

Conflicts in this codebase cluster in four tightly-coupled areas.

• Lesson directories under phases/ — When two contributors edit files in the same lesson’s code/, docs/, or outputs/ folders, Git cannot auto-merge the content. Combine the changes manually, then re-run the lesson’s tests to confirm everything still works.
• README.md — The lesson-link table uses a strict markdown row format. Adding or renaming lessons on the same table row causes overlapping edits.
• ROADMAP.md — The phase and lesson status table is updated in parallel by different feature branches.
• site/data.js — This file is generated by site/build.js from the README links; mismatched or missing rows after a merge break the site catalog until CI rebuilds it.

Step-by-Step Merge Conflict Resolution Workflow

The following process is the standard workflow defined in the repository's AGENTS.md file.

1. Pull the Latest main and Start the Merge

From your feature branch, synchronize with upstream before attempting any resolution.

git fetch origin main
git merge --no-edit origin/main

If Git reports conflicts, the merge pauses and marks the affected files for manual review.

2. Locate the Conflicted Files

Use git status to surface every file that still contains conflict markers.

git status

Typical conflicted paths include README.md, ROADMAP.md, and lesson content under phases/*/docs/en.md or phases/*/code/*.

3. Resolve Conflicts Manually

Open each conflicted file in your editor. For every <<<<<<< / ======= / >>>>>>> block:

1. Identify the intended final content. If a lesson was renamed, keep the new path and update the corresponding README.md link.
2. If two contributors added different lessons on adjacent rows, insert both rows in the correct alphabetical or numerical order.
3. Delete all conflict markers and save the file.

The README.md rows must match the exact markdown link format expected by site/build.js. Any deviation in path or punctuation produces a blank catalog entry on the website. The correct row format looks like this:

| 01 | [Linear Algebra Intuition](phases/01-math-foundations/01-linear-algebra-intuition/) | Learn | Python, Julia |

4. Re-run the Repository Maintenance Scripts

After manual editing, use the provided helper scripts to synchronize counts and structure.

Verify and auto-fix the lesson-count badges in README.md:

python3 scripts/check_readme_counts.py --fix

Audit lesson directories to enforce the one-commit-per-lesson rule:

python3 scripts/audit_lessons.py

Both scripts run in the CI pipeline defined in .github/workflows/curriculum.yml, so passing them locally prevents later build failures.

5. Commit the Resolved Changes

Stage the files you edited and commit the resolution separately from your original feature work.

git add README.md ROADMAP.md phases/
git commit -m "fix: resolve merge conflicts in <lesson-or-doc>"

Do not squash this resolution commit with the original lesson commit. The curriculum invariant requires each lesson to remain an atomic, isolated commit.

6. Push and Let CI Finish

Push the branch and allow the automated curriculum pipeline to validate the fix.

git push origin <your-branch>

The .github/workflows/curriculum.yml workflow will re-run audit_lessons.py, rebuild the site using site/build.js, update site/data.js on main, and auto-correct any remaining README count drift. If CI still reports errors, repeat steps 2 through 5 until the pipeline passes.

7. Optional: Manual Site Rebuild

For an immediate local preview after merging, regenerate the site catalog manually:

cd site
node build.js

This updates site/data.js with the correct lesson URLs derived from the current README.md links.

Automated Cleanup Script for Large Pull Requests

When a large pull request touches many lessons, you can use the following bash snippet to strip conflict markers from README.md while preserving both sides of the conflict. Run this before committing the final fix.

#!/usr/bin/env bash

# remove conflict markers from README.md while preserving both sides

awk '
  /^\<\<\<\<\</ {conflict=1; next}
  /^\=\=\=\=\=/ {next}
  /^\>\>\>\>\>/ {conflict=0; next}
  !conflict
' README.md > README.fixed.md && mv README.fixed.md README.md

After running the script, review the file to ensure each row follows the required markdown link format, then execute python3 scripts/check_readme_counts.py --fix to realign the badge totals.

Summary

• Merge conflicts in rohitg00/ai-engineering-from-scratch most often appear in README.md, ROADMAP.md, lesson directories under phases/, and the generated site/data.js catalog.
• Always preserve the one-commit-per-lesson rule when resolving conflicts; never squash the resolution commit into a lesson commit.
• Use git fetch origin main and git merge --no-edit origin/main to start resolution, then edit out all <<<<<<< / ======= / >>>>>>> markers.
• Run python3 scripts/check_readme_counts.py --fix and python3 scripts/audit_lessons.py locally to validate structure before pushing.
• Let the .github/workflows/curriculum.yml CI pipeline rebuild site/data.js and auto-fix counts automatically after your push.

Frequently Asked Questions

What causes most merge conflicts in the AI Engineering from Scratch repository?

Most conflicts arise because the curriculum tightly couples lesson folders under phases/ with the README.md link table and the ROADMAP.md status table. When two pull requests add, rename, or reorder lessons simultaneously, they edit the same metadata rows and collide during merge.

How do I fix a conflict in the README.md lesson table?

Open README.md, locate every <<<<<<< block, keep the correct lesson links in the exact markdown row format, remove the conflict markers, and save. Afterward, run python3 scripts/check_readme_counts.py --fix to update badge totals and ensure site/build.js can still parse the catalog.

Why should I avoid squashing the merge-conflict resolution commit?

The repository enforces a strict invariant where each lesson maps to exactly one dedicated commit. Squashing the resolution into a lesson commit violates that rule and breaks the atomic history expected by scripts/audit_lessons.py and the CI pipeline in .github/workflows/curriculum.yml.

How do I rebuild the site catalog after resolving conflicts?

The easiest path is to push your branch and let the CI workflow rebuild site/data.js automatically. If you need an immediate local preview, run node site/build.js from the repository root; this regenerates the catalog from the current README.md links so you can verify the site renders correctly before pushing.

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