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

Описание и применение

Использование изолированного worktree и структурированного пакета воспроизводимости ускоряет проверку PR в OSS, снижая количество неудачных CI‑запусков и упрощая принятие решений.

Задача

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.

Результат

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.

Рабочий процесс

• 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

Доказательства

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

Источник

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.

Источник