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

> Easily resolve merge conflicts in README.md, ROADMAP.md, and site/data.js for ai-engineering-from-scratch. Learn to accept main branch versions and regenerate files for consistency.

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

---

**Use `git checkout --theirs` to accept the main branch versions of [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), then regenerate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) that ensures [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) remains the source of truth while [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)**: A JSON-style data file consumed by the website, produced by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) which walks [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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:

```bash
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:

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

```

Optionally, verify the catalog structure with:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md):

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

```

### 5. Handle ROADMAP.md (If Applicable)

If [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) using `git checkout --theirs` to ensure the lesson table remains the source of truth.
- **Regenerate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)** by running `node site/build.js` after fixing [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) conflicts by accepting the main branch version or carefully reconciling status rows.
- **Avoid manual editing** of the generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file, as it is an artifact produced from [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) content.

## Frequently Asked Questions

### What causes merge conflicts in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)?

Conflicts occur because [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) is a generated file produced by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) parsing [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md). When two branches modify lesson structures or add new phases, both generate different versions of [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) to contain empty entries.

### What happens if I don't run `node site/build.js` after resolving [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)?

If you skip the regeneration step, [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) will contain stale data or conflict markers that do not reflect the current [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) when the status matrix differs?

Treat [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) similarly to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.