Match the Repo Test Dialect Before an OSS Patch Leaves the Fork

A first-time contributor cloned a popular HTTP client on a Sunday evening and reproduced a timeout bug. The crash appeared only when a redirect chain mixed HTTP/2 frames with a stale connection pool. The patch looked small in the editor, yet the project's CI matrix covered three language versions and two TLS backends. Maintainers bounced the pull request because the new test used a helper name that did not exist in the suite.

This composite scene shows up in public trackers even when the functional fix itself is technically correct. Reviewers then spend scarce maintainer time teaching house style instead of judging the intended behavior change. A merge packet that freezes the failing assertion, shadows the upstream job, and checks dialect cuts that extra round trip. The workflow treats a free coding model as a dialect reviewer rather than as the author of production code.

Why dialect mismatches stall otherwise valid patches

Open-source test suites accumulate local verbs, fixture factories, and assertion helpers that never appear in tutorials. A new file that imports unittest mock patterns into a pytest house, or the reverse, reads like a drive-by rewrite. Continuous integration then fails on collection errors long before it can exercise the regression the patch claims to close. Maintainers reasonably ask for a rewrite because they cannot tell a real fix from a second coding style landing in tree.

House dialect is not the same thing as clean code in the abstract. Neighboring tests already show how the project fakes time, sockets, clocks, and HTTP backends. Copying that local grammar keeps the review focused on behavior instead of on renaming helpers under discussion. The fork should learn that grammar before any model is invited to comment on the diff.

Build a merge packet on the fork

The packet is a small directory that travels beside the branch and survives a clean clone of the public fork. It stores a frozen assertion, a CI test selector, a dialect sample, and the rebased candidate diff. Maintainers can replay those files after checkout without reconstructing the original laptop or the container image. The same packet is the only context a free model should receive during a later dialect review pass.

Packet layout

Place the files under .merge-packet/ and keep them untracked or tracked, according to the project's ignore rules:

• assertion.lock — failing node id, exact assertion text, and captured at SHA
• selector.txt — the CI test command copied from the workflow or Makefile
• base.sha — default-branch commit that the selector was last proven against
• dialect_sample.md — excerpts from three nearby tests, with repository paths
• patch.diff — behavior change plus matching test, rebased onto the default branch
• review_checklist.md — allowed dialect findings, isolation notes, and rollback path

Step 1 — Freeze one assertion, not the entire CI log

Contributors should copy the failing node id and the exact assertion text into assertion.lock before editing production files. Full logs mix compiler warnings, retry noise, and unrelated suite failures that hide the contract under review. A frozen message becomes the oracle that later tests must fail before the patch and pass after the patch. If the suite cannot address that node in isolation, the contribution is not ready for a model-assisted review.

The following file is a template, not a capture from a live upstream run:

# .merge-packet/assertion.lock
# Template only — replace with values from the local failing node.
node_id: tests/client/test_redirects.py::test_timeout_on_stale_pool
assertion: >
  AssertionError: expected ReadTimeout after stale HTTP/2 pool reuse,
  got 200 from redirected origin
captured_at: 2026-09-22T00:00:00Z
notes:
  - Fail this node on the default branch before applying patch.diff.
  - Pass this node on the branch after patch.diff lands.

Step 2 — Copy the upstream selector from the workflow file

Most projects already declare the test command inside GitHub Actions, GitLab CI, or a Makefile target. The fork should run that same selector rather than a personal pytest invocation with extra flags and random markers. Shadowing the job catches missing extras, skipped markers, and environment variables that never appear in README snippets. The selector belongs in selector.txt so a reviewer can see the exact command without opening the workflow history.

#!/usr/bin/env bash
# .merge-packet/shadow_ci.sh
# Template only — not executed against a live upstream in this article.
set -euo pipefail

ROOT="$(git rev-parse --show-toplevel)"
PACKET="${ROOT}/.merge-packet"
cd "${ROOT}"

git rev-parse HEAD > "${PACKET}/head.sha"
BASE="$(tr -d '\r' < "${PACKET}/base.sha")"
echo "shadowing selector against recorded base ${BASE}"

SELECTOR="$(tr -d '\r' < "${PACKET}/selector.txt")"
# Example selector.txt line:
# PYTHONPATH=src pytest tests/client/test_redirects.py::test_timeout_on_stale_pool -q
eval "${SELECTOR}"

Record the default-branch SHA before the first shadow run so later rebases have a comparison point. A green run against an unknown base does not prove that upstream collection will accept the new module path. Contributors should refresh base.sha whenever they merge or rebase onto the project's default branch. The packet then shows reviewers which tree the selector last executed against.

Step 3 — Sample three nearby tests as the dialect source

Dialect is easier to copy from neighboring files than from a style guide that the repository never actually follows. The sample should include fixture names, assertion helpers, time control, and how the suite talks to the network. Three files are enough to show repeated patterns without dumping the entire tests directory into a prompt window. A short extractor can print imports and assertion calls so the sample stays mechanical instead of hand-wavy.

# .merge-packet/extract_dialect.py
# Template only — unexecuted example for pytest-like suites.
from __future__ import annotations

import ast
from pathlib import Path

MARKERS = ("assert", "pytest", "fixture", "monkeypatch", "responses", "respx", "freezegun", "httpx")

def summarize(path: Path) -> str:
    tree = ast.parse(path.read_text(encoding="utf-8"))
    imports: list[str] = []
    asserts: list[str] = []
    for node in ast.walk(tree):
        if isinstance(node, ast.ImportFrom) and node.module:
            imports.append(f"from {node.module} import ...")
        if isinstance(node, ast.Assert):
            asserts.append(ast.get_source_segment(path.read_text(encoding="utf-8"), node) or "assert ...")
    kept_imports = [line for line in imports if any(m in line.lower() for m in MARKERS)]
    lines = [f"## {path.as_posix()}", "### imports"] + kept_imports[:12]
    lines += ["### assertions"] + asserts[:12]
    return "\n".join(lines) + "\n"

if __name__ == "__main__":
    neighbors = [
        Path("tests/client/test_redirects.py"),
        Path("tests/client/test_pool.py"),
        Path("tests/client/test_timeouts.py"),
    ]
    Path(".merge-packet/dialect_sample.md").write_text(
        "\n".join(summarize(p) for p in neighbors if p.exists()),
        encoding="utf-8",
    )

Choose neighbors by directory, not by popularity of the helper names. A timeout bug in the HTTP client should sample other client tests rather than unrelated CLI snapshot tests. Generated golden files are a weak dialect source because they hide the assertions that humans actually review. If the suite is generated, freeze one generated output and say so inside dialect_sample.md.

Step 4 — Isolate the patch from drive-by refactors

Reviewers reject mixed diffs that reformat imports, rename locals, and fix the bug inside a single commit. The candidate patch.diff should contain the behavior change and the matching test, rebased onto the default branch. Formatting and comment cleanups belong in a follow-up issue if the project even wants them at all. Isolation makes the dialect review cheaper because the model is not asked to judge unrelated churn.

# Template only — produce a reviewable diff after tests match dialect.
git fetch origin
git rebase origin/main
git diff origin/main...HEAD -- . ':!.merge-packet' > .merge-packet/patch.diff

The test added for the frozen assertion should sit next to those three neighbor files. New support helpers need a name already used in the sample, or a short note explaining why a new helper is required. Private modules that neighboring tests never import should stay out of the new file. That rule prevents the patch from widening the public test surface by accident.

Step 5 — Run a dialect review on free model access

A contributor who already uses MonkeyCode can run the dialect review through free model access and the free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The model should receive the merge packet only, not a dump of unrelated files from the working tree. Human maintainers remain the merge authority, and the model output is a checklist of dialect mismatches.

The prompt below is a labeled template. It asks for findings, not for a rewritten production patch, and it forbids inventing helpers that the sample does not contain.

You are reviewing an OSS merge packet for test dialect only.
Read assertion.lock, selector.txt, dialect_sample.md, and patch.diff.
Do not invent fixtures, helpers, or modules that dialect_sample.md does not show.
Return markdown with these headings only:
1. Dialect mismatches (file:line, nearby pattern, required change)
2. Isolation issues (drive-by refactors, unrelated renames)
3. Oracle check (does the new test target assertion.lock?)
4. Rollback note (how to revert without leaving the new helper)
If evidence is missing, say "unknown" instead of guessing house style.

Allowed findings stay narrow so the human can apply them without a second design debate:

1. Unknown helper or fixture name that the sample never uses.
2. Wrong fixture scope, including function versus module setup that neighbors avoid.
3. Real network calls where neighboring tests fake HTTP, TLS, or DNS.
4. Test file location that does not match the package layout in the sample.
5. Assertion style drift, such as raw == where the house wraps pytest.raises.

Replay the packet after every rebase

Rebases rewrite context lines, so the frozen assertion and the shadowed selector must run again after each rebase. A green local run against an old default branch is not evidence that upstream CI will collect the new test. The packet should record the default-branch SHA beside the selector so reviewers can see the exact base. If the assertion text drifts after rebase, the oracle is stale and the contributor must freeze a new message.

Store a short replay log next to the selector rather than pasting terminal color codes into the pull request. One passing line and one failing line, taken from the isolated node, are enough evidence for most maintainers. Timestamp the replay against base.sha so later comments do not argue about an obsolete tree. The pull request body can link the packet path instead of embedding a screenshot of an entire CI log.

Decision table

Signal on the fork	Action	Stop the PR if
Frozen assertion missing	Capture node id before editing production files	The suite cannot isolate the node
Selector differs from CI	Copy the command from the workflow file	The job needs secrets or private images
Dialect sample empty	Extract three neighbor tests	Tests are generated and have no assertions
Diff includes rename or format-only hunks	Split commits and regenerate patch.diff	The bugfix cannot be rebased alone
Model flags a helper mismatch	Rewrite the test to match dialect_sample.md	Production code needs an API redesign
Oracle still fails after the patch	Do not open the pull request	The frozen message no longer matches reality

Limitations

The workflow does not replace a maintainer reading the production change or checking license headers and security notes. Free model access can miss project-specific macros, generated fixtures, or custom pytest plugins that a sample will under-represent. Shadowing CI still fails when the upstream job needs secrets, hardware, or proprietary containers the fork cannot reproduce. None of the commands above were executed against a live upstream repository for this article, so treat them as templates.

Model review also cannot certify performance, licensing, or ABI promises. A dialect match only says the new test looks like the house, not that the patch is the right architectural change. Contributors still need the project's contributing guide, code of conduct, and any required test matrix beyond the single frozen node. Treat model output as a pre-submit lint for tests, not as a substitute for maintainer judgment.

Who should skip this approach

• One-line documentation or typo pull requests with no test change.
• Embargoed security fixes that must not land on a shared public server.
• Changes that require proprietary hardware, licensed protocol dumps, or private containers.
• Repositories that already enforce dialect with formatters, custom linters, and coverage gates.

Contributors sending one-line documentation fixes do not need a merge packet or a model review loop. Embargoed security patches should stay off public free servers until the project's disclosure process is complete. Newcomers who cannot run the upstream selector locally should ask for a repro harness instead of guessing dialect from chat. Teams that already enforce dialect with linters and coverage gates can keep those tools and skip the model pass.

Keep the oracle and the selector even without a model

The Sunday bounce was not about intelligence or effort; it was about landing a foreign test dialect in a living suite. A frozen assertion, a shadowed CI selector, and a three-file dialect sample give maintainers something they can replay. The merge packet remains useful if every model mention is removed, because the oracle and the selector are the artifacts. Readers who already have free model access nearby can run the dialect checklist there and still keep humans as the merge gate.