Versionsregression eingrenzen

Version Regression Isolation

When to Use

Use when a feature or workflow that previously worked is now broken ("worked in v1.4, broken on main") and you need to identify the exact commit or dependency change that introduced the regression.

Preconditions Before Bisecting

git bisect only works reliably when the reproduction test is deterministic and fast:

1. Build an automated reproduction test or script (stored outside the tracked git tree, e.g., /tmp/repro-check.sh or an untracked test script) that exits with:
   • 0 when the behavior is good (bug absent).
   • 1 (up to 124, 126, 127) when the specific bug signature is present.
   • 125 (git bisect skip) when the current commit cannot be built or fails due to an unrelated broken build/migration.
2. Verify the script manually on both endpoints before starting bisect:
   • Known bad commit (e.g., HEAD): script exits 1 with the target bug signature.
   • Known good commit (e.g., last release tag or HEAD~50): script exits 0.

Targeted git log Narrowing (Faster Than Full Repo Bisect)

Before bisecting hundreds of commits across the whole repository, narrow the candidate commits by path or symbol:

• git log -S "<symbol_or_error>" --oneline -- <path> (pickaxe search for added/removed occurrences).
• git log -L :<functionName>:<filePath> (trace the evolution of a specific function).
• git log <good-ref>..<bad-ref> --oneline -- <affected-dir-or-files>: If only 3 commits touched the affected module between <good> and <bad>, inspect and test those 3 commits directly!

Automated git bisect run Workflow

When the regression spans many commits or non-obvious transitive callers:

1. Ensure a clean working tree (git status).
2. Start bisect scoped to relevant paths when appropriate:

   git bisect start <bad-commit> <good-commit> -- <optional-paths>
   git bisect run /path/to/repro-script.sh
   

3. Watch for Dependency & Schema Drift Across Commits:
   • If package-lock.json / pnpm-lock.yaml or database migrations changed between <good> and <bad>, the bisect script must account for dependency resolution or skip incompatible schema states (exit 125).
4. Always Clean Up Bisect State:
   • Run git bisect reset immediately after identifying the first bad commit so the repository is returned to its original branch/HEAD.

Reporting the First Bad Commit

Report:

1. The exact first bad commit SHA, author date, and commit message.
2. Which specific hunk (file:line) in that commit altered the precondition, query, type, or dependency version that triggered the bug.
3. Verification that <first-bad-commit>~1 passes the reproduction check while <first-bad-commit> fails with the exact bug signature.