Conflict Resolution Process for README, data.js, and catalog.json in AI Engineering From Scratch

The rohitg00/ai-engineering-from-scratch repository defines a strict three-step regeneration workflow in AGENTS.md to resolve merge conflicts in README.md, site/data.js, and 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 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.

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

Conflict Resolution Process for README.md

The 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.

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 file is a generated artifact produced by 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.

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 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.

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.

git push origin <your-branch>

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 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 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 file is a generated artifact created by 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 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 file at the repository root. This document specifies the exact helper scripts—scripts/build_catalog.py, scripts/check_readme_counts.py, and site/build.js—and the precise git checkout --theirs commands required for each artifact.

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