# Conflict Resolution Process for README, data.js, and catalog.json in AI Engineering From Scratch > Learn the conflict resolution process for README, data.js, and catalog.json in AI Engineering From Scratch. Explore the three-step regeneration workflow for efficient merge conflict management. Optimize your AI development work... - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: how-to-guide - Published: 2026-06-13 --- **The `rohitg00/ai-engineering-from-scratch` repository defines a strict three-step regeneration workflow in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) to resolve merge conflicts in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), and [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) by accepting the upstream version and rebuilding derived files with specific helper scripts.** The open-source educational project maintains synchronization between human-readable documentation and auto-generated website assets through a standardized **conflict resolution process for README, data.js, and catalog.json**. When multiple contributors add lessons simultaneously, overlapping changes in the lesson index and generated data files require regeneration rather than manual merging. The canonical procedures are documented in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file and rely on Python and Node.js helper scripts to ensure consistency. ## Prerequisites: Synchronize with Main Before resolving any conflicts, synchronize your branch with the latest upstream state to ensure you are resolving against the current source of truth. ```bash git fetch origin main git merge --no-edit origin/main ``` ## Conflict Resolution Process for README.md The [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) file contains a table of lesson links that frequently conflicts when pull requests add new lessons to the same section. Since the file is both human-edited and programmatically consumed, the resolution requires regeneration. ### Resolution Steps 1. **Accept the upstream version** of the README to capture the latest lesson list. 2. **Regenerate the catalog** using the build script. 3. **Fix lesson-count mismatches** with the verification tool. 4. **Stage the updated file** for commit. ```bash git checkout --theirs README.md python3 scripts/build_catalog.py python3 scripts/check_readme_counts.py --fix git add README.md ``` ## Conflict Resolution Process for site/data.js The [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file is a generated artifact produced by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js). Conflicts arise when two branches modify lesson markup, causing the generated URLs to diverge and producing unreadable merge conflicts in the JavaScript output. ### Resolution Steps Accept the upstream version and rebuild the file to ensure URL consistency and valid JavaScript syntax. ```bash git checkout --theirs site/data.js node site/build.js git add site/data.js ``` ## Conflict Resolution Process for catalog.json (Legacy) Although [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) is git-ignored in current branches, legacy branches may still contain the file. A merge can reintroduce this stale artifact, requiring removal rather than regeneration. ### Resolution Steps Remove the file from the index and commit the deletion. The continuous-integration pipeline will recreate a fresh catalog on the next build. ```bash git rm catalog.json git commit --no-edit ``` ## Finalizing the Merge After executing the artifact-specific resolution steps, complete the workflow by pushing the resolved branch to the remote repository. ```bash git push origin ``` ## Summary - **Always synchronize first**: Run `git fetch origin main` and `git merge --no-edit origin/main` before attempting resolution. - **README.md**: Accept the upstream version with `git checkout --theirs`, regenerate using `python3 scripts/build_catalog.py`, fix counts with `python3 scripts/check_readme_counts.py --fix`, then stage. - **site/data.js**: Accept the upstream version with `git checkout --theirs`, rebuild with `node site/build.js`, then stage. - **catalog.json**: Remove legacy instances using `git rm catalog.json` and commit with `git commit --no-edit`; CI handles regeneration. ## Frequently Asked Questions ### How does the repository handle conflicts in the README.md file? According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) guide in `rohitg00/ai-engineering-from-scratch`, you must accept the *theirs* version using `git checkout --theirs README.md`. This preserves the upstream lesson list, after which you regenerate the catalog with [`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py) and fix stale lesson counts using `scripts/check_readme_counts.py --fix`. ### Why should I regenerate site/data.js instead of manually editing the conflict? The [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file is a generated artifact created by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js). When branches modify lesson markup, the generated URLs diverge, producing complex conflicts that are prone to human error. The official process requires accepting the upstream version and rebuilding to ensure the JavaScript data structure remains valid and consistent with the current README. ### What is the correct way to resolve a catalog.json merge conflict? Since [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) is git-ignored in current branches but may exist in legacy branches, you should remove it from the index using `git rm catalog.json` and commit with `git commit --no-edit`. The CI pipeline will automatically recreate a fresh catalog during the next build, eliminating the need for manual regeneration. ### Where are the official conflict resolution instructions documented? The canonical **conflict resolution process for README, data.js, and catalog.json** is defined in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file at the repository root. This document specifies the exact helper scripts—[`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.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)—and the precise `git checkout --theirs` commands required for each artifact.