Freeze the Issue Thread: Numbered Criteria Before an OSS Patch

Description and use

Creating a frozen, numbered contract ensures contributors implement the exact issue requirements, preventing mis‑patches and regressions.

Problem

Open‑source issue threads become noisy and ambiguous, leading to patches that fix the wrong problem or introduce regressions.

Outcome

Patches are aligned with a clear, testable contract, reducing mis‑patches and regressions. The workflow enforces reproducibility, environment consistency, and diff scope.

Workflow

• Read issue thread and identify key comments
• Create ISSUE_CONTRACT.md with MUST, SHOULD, WONTFIX sections, numbering each item and pinning environment
• Clone repo and checkout frozen SHA
• Run tests to confirm MUST failures (e.g., M2)
• Create a dedicated branch for the fix
• Edit only files listed in MUST (e.g., libretry/retry.py)
• Run local gate script to ensure no disallowed paths are changed
• Add failing test for M1 if not present
• Commit changes, push, and include contract checklist in PR body
• Reviewers verify contract, test failures, and diff scope before approving

Evidence

The packet lives beside the clone, usually as ISSUE_CONTRACT.md, and it is committed only if the project already stores review notes.

Source

Reproduction is the first implementation of the contract, and it should fail in the way M2 describes.

Source