How to Validate Local Changes Before Pushing to rohitg00/ai-engineering-from-scratch

Run the three-step validation suite—curriculum audit, README counter verification, and unit tests—to ensure every lesson passes structural and functional validation before pushing to the repository.

Contributing to the rohitg00/ai-engineering-from-scratch curriculum requires strict validation of local changes to maintain repository integrity. Before you push any modifications, you must validate local changes against the automated workflow that checks documentation, metadata consistency, and code functionality. The validation pipeline runs entirely on your workstation and must exit with code 0 before you commit.

The Three-Step Validation Workflow

The repository provides automated scripts in scripts/ that enforce curriculum invariants. Each step must return exit code 0 before you commit or push.

Step 1: Audit the Curriculum Structure

The audit_lessons.py script performs static analysis across all phases/*/* directories to catch naming, documentation, and schema violations.

In scripts/audit_lessons.py, the script validates:

• Lesson directory naming against the LESION_DIR_RE pattern
• Presence of docs/en.md containing a top-level H1 heading via check_docs_en_md
• Non-empty code/ directories via check_code_main
• quiz.json schema conformity via check_quiz
• Resolvable internal markdown links via check_internal_links

python scripts/audit_lessons.py

A clean run outputs audit_lessons.py — 503 lesson(s) checked, 0 issue(s) and exits with code 0. If issues exist, the script exits with code 1 and reports specific violations.

Step 2: Verify README Counters

The check_readme_counts.py script ensures hard-coded badge numbers in README.md match the canonical catalog.json totals, preventing drift in public lesson counts.

python scripts/check_readme_counts.py

If counts mismatch (e.g., README shows 502 lessons but catalog.json lists 503), the script reports specific discrepancies and exits with code 1. To automatically rewrite the README with correct counts, run:

python scripts/check_readme_counts.py --fix

Step 3: Run Unit Tests

Every lesson contains a tests/ directory validating its code/ implementation. Navigate to the specific lesson directory and execute the language-specific test runner.

For Python lessons:

cd phases/03-deep-learning-core/02-multi-layer-networks
python -m unittest discover -v

For TypeScript lessons:

npx tsx --test

For Rust lessons:

cargo test

For Julia lessons:

julia --project -e 'using Test; include("test/runtests.jl")'

All tests must pass with exit code 0 before pushing.

Summary

• Run the curriculum audit with python scripts/audit_lessons.py to check naming conventions, documentation H1 headers, quiz schemas, and internal links in phases/*/*/.
• Verify README counts using python scripts/check_readme_counts.py to ensure badge numbers match catalog.json totals; apply --fix for automatic correction.
• Execute unit tests in each lesson's tests/ directory using the appropriate language runner (Python, TypeScript, Rust, or Julia) as defined in the repository's AGENTS.md.
• Require exit code 0 from all three steps before committing; a non-zero status indicates blocking issues that must be resolved.
• Commit one lesson per commit when adding new content, ensuring each change passes the full validation suite.

Frequently Asked Questions

What does the audit script check for specifically?

The audit_lessons.py script validates directory naming against LESION_DIR_RE patterns, verifies every lesson contains docs/en.md with a top-level H1 via check_docs_en_md, ensures code/ directories are non-empty via check_code_main, validates quiz.json schema compliance via check_quiz, and confirms all internal markdown links resolve correctly via check_internal_links.

How do I automatically fix README badge count mismatches?

Run python scripts/check_readme_counts.py --fix to automatically rewrite the hard-coded badge URLs in README.md to match the actual totals in catalog.json. Without the --fix flag, the script only reports discrepancies and exits with code 1.

Which test command should I use for my specific lesson?

The test command depends on the lesson's implementation language found in phases/*/*/code/. For Python lessons, use python -m unittest discover -v. For TypeScript, use npx tsx --test. For Rust, use cargo test. For Julia, use julia --project -e 'using Test; include("test/runtests.jl")'.

Can I push changes if only one validation step fails?

No. All three steps must exit with code 0 before pushing. The repository's contribution policy requires that every change passes the curriculum audit, README count verification, and unit tests to prevent broken links, malformed quiz files, and failing code from entering the main branch.

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