Worktree Isolation for OSS Bugs: A Review Packet Maintainers Can Trust

Description and use

Using an isolated worktree and a structured reproducibility packet speeds up PR review in OSS, reduces CI failures, and clarifies the fix for maintainers.

Problem

Maintainers often reject pull requests that fail on CI because contributors do not isolate the failing command or provide reproducible evidence, leading to wasted time and confusion.

Outcome

Using an isolated worktree and a structured review packet reduces CI failures, speeds up review, and provides clear evidence for maintainers to accept or reject patches.

Workflow

• Clone the target repo and create a throwaway worktree at the issue commit using git worktree add and git switch -c
• Check out the exact revision referenced in the issue before installing dependencies
• Create a virtual environment and install the project in editable mode with extras as documented
• Capture the failing command in a script, run it, and record stdout, stderr, and exit code in .repro
• Truncate long logs to keep the packet readable
• Identify the modules imported by the failing command and search for relevant code changes
• Make the smallest possible patch that turns the command green, ensuring no unrelated files appear in git diff --stat
• Re-run the failing command after the patch to confirm exit status is zero and diff is minimal
• Build a review packet: a markdown file with reproduction details, truncated output, and a unified diff, excluding secrets and large directories
• Review the packet locally before uploading to the issue or PR
• Optionally quote relevant rules from CONTRIBUTING.md or test matrix
• Ensure the packet contains only necessary files and no sensitive data

Evidence

A useful packet answers four points with files rather than adjectives: Which worktree and commit reproduced the bug in isolation; Which exact command failed, including arguments and exit status; Which files the patch actually touches, shown as a unified diff; Which project rules constrain the change, quoted from tests or CONTRIBUTING

Source

The packet is a single markdown file plus the unified diff. It should be small enough to read in one sitting and free of secrets, absolute home paths, and vendor directories.

Source