Open an OSS Patch From a Checked Four-File Bundle

An open-source patch is not ready at the first green test. It is ready when four frozen files agree with each other. A pull request waits until a local checker accepts them.

Those files are the issue note and the repro log. The other pair is the patch file and the test log. A model may comment, but a maintainer still merges.

Hold the request until the bundle is complete

Each stage writes one file and then stops. A checker script blocks the request until those files exist. The contributor does not open the request from a chat summary.

A long chat thread hides the failing command and exact output. A maintainer cannot replay a paragraph of advice. A frozen bundle can be cloned, diffed, and run again.

The bundle lives beside the clone, not inside the product tree. That split keeps generated logs out of the product patch. The layout below is a proposed template for local use.

contrib-bundle/
  issue.md
  repro.sh
  repro.log
  patch.diff
  test.sh
  test.log
  review-notes.md
  check-bundle.sh

1. Write the issue note before editing code

The issue note states expected behavior in one short paragraph. It names the command that should fail on the current tree. It names the single file the contributor expects to change.

Keep the note under forty lines so the bug stays narrow. A long note often hides a second unrelated defect. Add the upstream issue URL when one already exists.

# Issue note

Command `python -m unittest tests/test_slug.py` fails.
Observed call returns hello-- with the trailing separators intact.
Expected result is hello with trailing separators removed.
Suspected file is pkg/slug.py only.
Upstream issue: replace this line with the real URL.

Create the bundle directory before the first command runs. Keep that directory outside the product commit on purpose. A later status check should ignore the bundle path.

mkdir -p contrib-bundle
printf '%s\n' '# Issue note' > contrib-bundle/issue.md

2. Freeze a reproduction that exits non-zero

Place the product clone in a sibling directory named repo. The sample scripts resolve that path from their own folder. Change the path if the clone uses another directory name.

The repro script must exit non-zero on the unpatched tree. It must print the observed value with a stable marker. It must not edit source files or install new packages.

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/../repo"
python - <<'PY'
from pkg.slug import slugify
got = slugify('Hello--')
print('observed=' + got)
raise SystemExit(0 if got == 'hello' else 1)
PY

Run the script once and redirect both streams into the log. Do not edit that log by hand after the run. A hand-edited log will not match a later run.

chmod +x contrib-bundle/repro.sh
./contrib-bundle/repro.sh > contrib-bundle/repro.log 2>&1 || true
test -s contrib-bundle/repro.log
grep -n '^observed=' contrib-bundle/repro.log

The failure guard keeps the shell alive after a real miss. The log must still contain the observed marker line. A missing marker means the script never reached the bug.

This script is an unexecuted example, not a measured run. Adapt the import path before using it on a real clone. Replace the sample if the project exposes another entry point.

3. Export a diff that stays on one path

Change only the suspected file during this pass. Stage nothing else before exporting the unified diff. Write that diff into the bundle under a fixed name.

cd repo
git diff -- pkg/slug.py > ../contrib-bundle/patch.diff
test -s ../contrib-bundle/patch.diff
git diff --stat -- pkg/slug.py

Reject the diff when it touches lockfiles or generated assets. Reject it when unrelated docs change in the same hunk set. A wide diff is a new task, not a review bundle.

The sample below is an illustration, not a tested upstream fix. The real project may already collapse repeated separators. Replace the sample with the actual diff from git.

--- a/pkg/slug.py
+++ b/pkg/slug.py
@@
 def slugify(value):
-    return value.strip().lower().replace(' ', '-')
+    text = value.strip().lower().replace(' ', '-')
+    while '--' in text:
+        text = text.replace('--', '-')
+    return text.strip('-')

4. Record the test command and the full log

The test script runs the narrow test or the full suite. It writes stdout and stderr into one log file. Its exit status must match the test runner status.

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/../repo"
python -m unittest tests/test_slug.py

set +e
./contrib-bundle/test.sh > contrib-bundle/test.log 2>&1
status=$?
set -e
printf 'exit=%s\n' "$status" | tee -a contrib-bundle/test.log
test "$status" -eq 0

Read the full log before asking any model for notes. A green summary with a skipped test is not success. Record skips in the issue note instead of hiding them.

5. Redact the bundle before it leaves the machine

Search the bundle for obvious secret markers before any upload. Keep env files and private keys out of that directory. A hosted review is optional, and a leaked secret is not.

grep -RInE 'API_KEY|SECRET|TOKEN|PASSWORD|BEGIN PRIVATE' contrib-bundle && echo 'stop: possible secret' || echo 'no-obvious-secrets'
find contrib-bundle -name '.env' -o -name '*.pem' -o -name 'id_rsa'

The search is a tripwire, not a complete secret scanner. It will miss renamed credentials and encoded blobs. The contributor still reads every diff line before upload.

6. Gate the request with a shape checker

The checker does not understand the bug itself. It only enforces bundle shape and a few markers. That limit is enough to stop a half-finished upload.

Edit the suspected path inside the checker before the first run. The sample path is only pkg/slug.py and will miss most repos. A hardcoded path is useful because the scope stays explicit.

#!/usr/bin/env bash
set -euo pipefail
root="$(cd "$(dirname "$0")" && pwd)"
need=(issue.md repro.sh repro.log patch.diff test.sh test.log)
for f in "${need[@]}"; do
  test -s "$root/$f" || { printf 'missing:%s\n' "$f"; exit 1; }
done
grep -q '^diff --git ' "$root/patch.diff" || { echo 'not-a-diff'; exit 1; }
grep -q '^observed=' "$root/repro.log" || { echo 'no-observed-marker'; exit 1; }
if grep -E '^\+\+\+ b/' "$root/patch.diff" | grep -v 'b/pkg/slug.py' | grep -q .; then
  echo 'diff-out-of-scope'
  exit 1
fi
if find "$root" -type f -size +200k | grep -q .; then
  echo 'file-too-large'
  exit 1
fi
echo 'bundle-ok'

Run the checker before any pull request command. Stop when the script prints anything other than success. Fix the named file, then rerun the checker from scratch.

chmod +x contrib-bundle/check-bundle.sh
./contrib-bundle/check-bundle.sh

The size cap is a local reading policy, not a host limit. Raise it only after a maintainer asks for a larger log. Generated coverage pages do not belong in this folder.

7. Ask a model to review the four frozen files

A model review helps when the input is the frozen bundle. It gets noisy when the input is the entire checkout. Attach the note, both logs, the diff, and the test script.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access can read that small bundle. Its free server option can host the review away from tests.

No quota, model name, or hardware figure is stated here. Those details change and belong on the current product page. Confirm both options there before treating them as available.

Use one fixed prompt and store the reply beside the logs. Do not treat that reply as a merge approval. A later human still compares the notes against both logs.

Review this local contribution bundle only.
Read issue.md, repro.log, patch.diff, and test.log.
List mismatches between the issue note and the diff.
List claims that test.log does not actually show.
Do not claim the patch is correct.
Do not propose new features.
End with: human maintainer decides.

That prompt is a proposal, not a scored evaluation. Discard the reply when it invents a path absent from the diff. Rerun with the same four files rather than the whole repo.

8. Assign each check to one owner

Some checks are mechanical, and some must stay human. The table below assigns one owner to each check. Hosted model notes stay inside the advisory row only.

Check	Owner	Rule
Bundle files exist and are non-empty	Checker	Missing files block the request.
Repro log contains the observed marker	Checker	A silent log is not a reproduction.
Diff starts with a git diff header	Checker	A note file is not a patch.
Diff stays on the suspected path	Checker	Extra paths start a separate task.
Test log shows no hidden skips	Human	Runners phrase skips in different ways.
Patch style looks consistent	Model note, then human	Style notes stay advisory.
Project will accept the design	Maintainer	A model cannot speak for the project.
Secrets stay out of the bundle	Contributor	Never upload tokens or private keys.

The hosted review is for notes, not for the test suite. Keep the passing test log on the machine that produced it. A remote comment never replaces that local evidence.

9. Name the limits before requesting review

This bundle does not prove thread safety or load behavior. It does not cover bugs that need private credentials. Leave those cases on a maintainer-approved private repro.

A green test log can still miss a sibling package. The checker reads file shape, not coverage data. Add a coverage line only when the project already prints one.

Model notes can be wrong, stale, or simply overconfident. Keep each note dated inside the review file for comparison. Never paste model wording into the commit message as fact.

The two availability options are claims supplied for this draft. They are not a promise of capacity, speed, or future price. Read the current product page before relying on either option.

10. Skip the workflow when it outweighs the fix

Skip this workflow for a one-line documentation typo. Four frozen files would outweigh that small documentation change. Skip it when a failing test and target branch already exist.

Skip the model step when the diff holds secrets or customer data. Skip it for unpublished vulnerability details as well. Review those patches with a human on a trusted machine.

Skip any hosted server when the license bars third-party review. Read that license before uploading any project file. A convenient host does not grant permission to upload code.

11. Commit the product change, then open the request

After the checker succeeds, commit the product change only. Leave the bundle outside that commit unless fixtures were requested. Name the exact test command in the pull request body.

cd repo
git add pkg/slug.py tests/test_slug.py
git status --short
git diff --cached --stat
git commit -m 'Fix slugify trailing separator collapse'

A plain pull request body can stay short and concrete. It points at local evidence without claiming a model sign-off. The sample body below is a template, not a required format.

cat > contrib-bundle/pr-body.md <<'EOF'
## Local evidence

Repro command: ./contrib-bundle/repro.sh
Test command: python -m unittest tests/test_slug.py
Checker result: bundle-ok
Model notes, if any, stayed advisory and were not an approval.
EOF
gh pr create --title 'Fix slugify trailing separator collapse' --body-file ../contrib-bundle/pr-body.md

Do not write that a model approved the merge. Say the tests ran locally and name the command. Attach bundle paths as evidence notes, not as correctness proof.

Readers can use MonkeyCode's free model access for this review step. The free server option can host that pass away from the suite. Local tests and the maintainer still gate the merge.