Conflict Resolution Process for Merging Branches with catalog.json or README.md Changes

To resolve merge conflicts involving auto-generated artifacts in the rohitg00/ai-engineering-from-scratch repository, accept the main branch version for README.md and regenerate counts using the provided Python scripts, while simply removing legacy catalog.json files that are now git-ignored.

When contributing to the rohitg00/ai-engineering-from-scratch curriculum repository, pull requests that modify lesson content often trigger merge conflicts in automatically generated files. Understanding the conflict resolution process for merging branches with catalog.json or README.md changes ensures that the CI pipeline remains healthy and generated artifacts stay synchronized with the source of truth.

Why These Conflicts Occur

Generated artifacts in this repository drift out of sync because they are rebuilt automatically on every push to main, while feature branches may contain stale versions.

Legacy catalog.json Tracking

Although catalog.json is now git-ignored and no longer tracked in the repository, older branches may still include this machine-readable curriculum catalog. When these branches merge with main, Git flags a conflict that must be resolved by deleting the legacy file.

README.md Auto-Generation

The README.md contains a summary table with lesson-link rows that include automatically computed counts. The CI job readme-counts-sync rewrites these counts on every push to main. Consequently, any branch that manually modifies the table will conflict with the automated version.

Step-by-Step Conflict Resolution Process

The official procedure documented in AGENTS.md follows a specific workflow to ensure consistency across generated files.

1. Sync with the Latest main Branch

Always begin by fetching the most recent changes from the upstream repository to establish a clean merge base.

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

2. Handle catalog.json Conflicts (Legacy Only)

If Git reports a conflict in catalog.json, treat it as a legacy artifact that should be removed rather than merged.

# The file is git-ignored; simply drop it from the branch

git rm catalog.json
git commit --no-edit

3. Resolve README.md Conflicts

For conflicts in the README table, discard the branch version and regenerate the counts using the maintenance scripts.

Accept the version from main:

git checkout --theirs README.md

Recompute the lesson totals and fix the table:

python3 scripts/build_catalog.py          # Rebuilds the hidden catalog (optional)

python3 scripts/check_readme_counts.py --fix

Stage the corrected file:

git add README.md && git commit --no-edit

4. Handle site/data.js Conflicts (Optional)

If the generated site map conflicts, apply the same pattern: accept the main version and regenerate.

git checkout --theirs site/data.js
node site/build.js
git add site/data.js && git commit --no-edit

5. Push the Resolved Branch

Once all generated files are reconciled, push the clean branch to origin.

git push origin <your-branch>

Key Scripts and Automation

The repository provides specific utilities to maintain generated file consistency:

• scripts/check_readme_counts.py: Validates and fixes lesson-link row counts in README.md. The --fix flag automatically corrects discrepancies.
• scripts/build_catalog.py: Rebuilds the machine-readable curriculum catalog (optional step for catalog.json conflicts).
• site/build.js: Regenerates site/data.js from the README and ROADMAP sources.

These scripts are referenced in AGENTS.md under the conflict resolution section, which serves as the central policy guide for handling generated-file conflicts.

Summary

• Generated artifacts like README.md tables and catalog.json drift automatically when the main branch updates.
• Legacy catalog.json conflicts are resolved by running git rm catalog.json since the file is git-ignored.
• README.md conflicts require checking out the main version with git checkout --theirs README.md and regenerating counts via python3 scripts/check_readme_counts.py --fix.
• Site data conflicts follow the same pattern using git checkout --theirs site/data.js followed by node site/build.js.
• Always reference AGENTS.md in the repository root for the authoritative conflict resolution policy.

Frequently Asked Questions

Why does catalog.json cause conflicts if it is git-ignored?

Legacy branches created before catalog.json was added to .gitignore may still track the file. When these branches attempt to merge with modern main, Git detects the file presence as a conflict even though the current specification ignores it. The resolution is to explicitly remove the file from the branch index using git rm catalog.json.

What does the check_readme_counts.py script do?

The scripts/check_readme_counts.py utility validates that the lesson counts in the README.md summary table match the actual number of lesson files in the repository. When invoked with the --fix flag, it automatically recalculates and updates the table rows to reflect the current curriculum state, ensuring the documentation remains accurate without manual editing.

Can I manually edit the README.md table instead of using the script?

Manual editing is discouraged because the CI job readme-counts-sync will overwrite your changes on the next push to main. Using python3 scripts/check_readme_counts.py --fix ensures your counts match the automated logic used by the pipeline, preventing future conflicts and maintaining consistency with the generated site data.

Where is the official conflict resolution policy documented?

The definitive guide resides in AGENTS.md at the repository root, specifically within the conflict resolution section. This document outlines the exact commands for handling catalog.json, README.md, and site/data.js conflicts, and serves as the source of truth for contributors and automation agents alike.

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