diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1511edaa..ab486ca5 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -5,6 +5,10 @@ ## Evidence - Confusion, missing step, stale example, or bug this addresses: +- Bounty capacity and active attempts/open PRs checked: +- Intended files or surfaces: +- Expected PR size: +- Out of scope: ## Test Evidence diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 00e7b42e..baea8cf8 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -202,13 +202,15 @@ Use this checklist before opening a PR for `mrwk:bounty` issues: 1. Confirm no active claim or duplicate PR already covers the same scope. 2. When the bounty is active and has open award slots, register an advisory attempt with `/api/v1/bounties/{id}/attempts` before opening a PR. -3. Keep changes small and directly tied to one bounty issue. -4. Include `Bounty #` or `Refs #` in PR body. -5. Explain the exact user or maintainer pain point you fixed. -6. Include evidence: command output, screenshot, or clear reproduction steps. -7. Run the required checks from the issue text (for docs work, run +3. Write the claim-window scope before coding: exact bounty, intended files or + surfaces, expected PR size, test plan, and what is out of scope. +4. Keep changes small and directly tied to one bounty issue. +5. Include `Bounty #` or `Refs #` in PR body. +6. Explain the exact user or maintainer pain point you fixed. +7. Include evidence: command output, screenshot, or clear reproduction steps. +8. Run the required checks from the issue text (for docs work, run `./.venv/bin/python scripts/docs_smoke.py`). -8. Avoid private data, secret material, and speculative price claims. +9. Avoid private data, secret material, and speculative price claims. Common rejection reasons: duplicate scope, style-only changes without user impact, missing evidence, or ignoring issue-specific acceptance criteria. diff --git a/docs/bounty-rules.md b/docs/bounty-rules.md index c1b4028a..4f38f5da 100644 --- a/docs/bounty-rules.md +++ b/docs/bounty-rules.md @@ -80,6 +80,11 @@ PR bounty submissions should link the bounty issue with `Bounty #` or `Refs #`. Use a closing reference only when the issue should close after that PR. +For bounty PRs, include the claim-window packet in the PR body: exact bounty +reference, intended files or surfaces, expected PR size, test plan, evidence, +and out-of-scope notes. If the diff grows beyond the expected size, split it or +explain why the larger review remains focused. + Paid bounty links are tracked in [docs/paid-bounties.md](paid-bounties.md) and the public [GitHub discussion](https://github.com/ramimbo/mergework/discussions/16). diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py index f8fe1729..0b2de8c5 100644 --- a/scripts/docs_smoke.py +++ b/scripts/docs_smoke.py @@ -24,6 +24,7 @@ ] LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") DOCS_ISSUE_TEMPLATE = ".github/ISSUE_TEMPLATE/docs.yml" +PR_TEMPLATE = ".github/pull_request_template.md" def _local_target_exists(source: Path, target: str) -> bool: @@ -63,6 +64,13 @@ def main() -> int: if "link the page, docs file, heading, command, or ui path" not in template: print("docs issue template location prompt must request actionable evidence") ok = False + pr_template = ROOT / PR_TEMPLATE + if not pr_template.exists(): + print(f"missing pull request template: {PR_TEMPLATE}") + ok = False + elif "expected pr size:" not in pr_template.read_text(encoding="utf-8").lower(): + print("pull request template must ask for expected PR size") + ok = False if ok: print("docs smoke ok") return 0