How to Resolve Merge Conflicts in README.md, ROADMAP.md, and site/data.js for AI Engineering from Scratch

Use git checkout --theirs to accept the main branch versions of README.md and site/data.js, then regenerate site/data.js using node site/build.js to restore consistency across the curriculum's tightly coupled documentation files.

The rohitg00/ai-engineering-from-scratch repository maintains curriculum data across three interdependent files that frequently cause merge conflicts when multiple contributors modify lesson structures simultaneously. When Git signals a conflict in these files, attempting manual resolution risks breaking the website's data generation pipeline or corrupting the lesson catalog. The repository provides a canonical conflict resolution workflow documented in AGENTS.md that ensures README.md remains the source of truth while site/data.js stays synchronized.

Understanding the File Dependencies

The three files that drive the public view of the curriculum are tightly coupled and must remain in sync:

• README.md: The human-readable source of truth containing a markdown table of all lessons with specific link syntax ([Title](phases/NN-phase-slug/MM-lesson/)). The site builder parses these links to generate URLs.
• ROADMAP.md: A machine-readable status matrix tracking lesson completion states (WIP, ✅, etc.) using the same phase/lesson ordering as the README.
• site/data.js: A JSON-style data file consumed by the website, produced by site/build.js which walks README.md and extracts the markdown links. If links are missing or malformed, the generated file contains empty entries that break the site.

When a pull request modifies lesson order or adds new entries, Git raises merge conflicts because the three sources must stay aligned. The resolution strategy prioritizes the README.md from the main branch, then regenerates the dependent artifacts.

Step-by-Step Conflict Resolution

Follow this precise sequence to resolve conflicts without manual fiddling. This workflow is extracted from the Conflict resolution section of AGENTS.md.

1. Fetch and Merge the Main Branch

Bring your feature branch up to date with the remote main branch to surface the conflicts:

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

2. Resolve README.md Conflicts

Accept the version from main to ensure you have the correct lesson-link table and structure:

git checkout --theirs README.md

3. Fix Badge Counts and Lesson Numbering

Run the helper script to rewrite the badge counts and validate the lesson table integrity:

python3 scripts/check_readme_counts.py --fix
git add README.md

Optionally, verify the catalog structure with:

python3 scripts/build_catalog.py

4. Resolve site/data.js Conflicts

Accept the main branch version initially, then regenerate to ensure it matches the fixed README.md:

git checkout --theirs site/data.js
node site/build.js
git add site/data.js

5. Handle ROADMAP.md (If Applicable)

If ROADMAP.md also conflicted, use the same theirs strategy to keep the main branch status matrix, or manually edit to reconcile status rows before staging:

git checkout --theirs ROADMAP.md

# Or manually edit, then:

git add ROADMAP.md

6. Finalize the Merge

Commit the resolution without additional edits and push the resolved branch:

git commit --no-edit
git push origin <your-branch>

Automated CI Safety Nets

The repository runs two CI pipelines on every push to main that act as safety nets: readme-counts-sync and site-rebuild. These jobs automatically correct lingering mismatches by re-running scripts/check_readme_counts.py and node site/build.js. However, performing the manual steps above prevents CI from having to redo work and keeps your pull request clean and reviewable.

Summary

• Accept the main branch version of README.md using git checkout --theirs to ensure the lesson table remains the source of truth.
• Regenerate site/data.js by running node site/build.js after fixing README.md to synchronize the website data.
• Fix metadata using python3 scripts/check_readme_counts.py --fix to update badge counts and lesson numbering automatically.
• Apply the same strategy to ROADMAP.md conflicts by accepting the main branch version or carefully reconciling status rows.
• Avoid manual editing of the generated site/data.js file, as it is an artifact produced from README.md content.

Frequently Asked Questions

What causes merge conflicts in site/data.js?

Conflicts occur because site/data.js is a generated file produced by site/build.js parsing README.md. When two branches modify lesson structures or add new phases, both generate different versions of site/data.js, causing Git to flag the binary-like differences as unmergeable. The file should never be manually edited; instead, regenerate it from the canonical README.md.

Why should I use --theirs instead of manually merging the files?

Using git checkout --theirs README.md ensures you inherit the exact lesson table structure and link syntax from the main branch, eliminating the risk of malformed markdown links that would break the site builder. Manual merging risks introducing subtle syntax errors in the link patterns (e.g., [Title](phases/01-phase/01-lesson/)) that cause site/data.js to contain empty entries.

What happens if I don't run node site/build.js after resolving README.md?

If you skip the regeneration step, site/data.js will contain stale data or conflict markers that do not reflect the current README.md structure. This causes the website to display broken links or missing lessons, and the CI site-rebuild pipeline will generate a secondary commit to fix the mismatch, cluttering the repository history.

How do I handle conflicts in ROADMAP.md when the status matrix differs?

Treat ROADMAP.md similarly to README.md by running git checkout --theirs ROADMAP.md to accept the main branch's status matrix. If your branch introduced new lessons that need status entries, manually edit the file after checking out theirs to add the new rows while preserving the existing status markers from main.

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