Skip to content

docs: make PR descriptions plain-language first - #77

Merged
hannesrudolph merged 1 commit into
mainfrom
docs/plain-english-pr-template
Sep 14, 2026
Merged

hannesrudolph merged 1 commit into
mainfrom
docs/plain-english-pr-template

Conversation

@roboclaw-bot

Copy link
Copy Markdown
Contributor

What Problem This Solves

PR authors need clearer guidance to explain the problem and outcome without a long technical introduction.

User Impact

User impact: contributors are prompted to put the concrete outcome first and keep risks, migrations, required actions, and useful evidence visible. No product behavior changes.

Why This Change Was Made

Carry over the approved wording from openclaw/openclaw#146253 while preserving the existing section names and maintainer-edit requirement.

Evidence

  • Compared the live template with the original; no repository-specific additions were lost.
  • Checked the replacement against the approved template, reviewed the diff, and ran git diff --check successfully.
  • Reviewed repository guidance and PR workflows. Runtime tests were not run for this template-only change.

Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
@clawsweeper

clawsweeper Bot commented Sep 12, 2026 •

Copy link
Copy Markdown

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@roboclaw-bot
roboclaw-bot marked this pull request as ready for review September 12, 2026 19:41
@clawsweeper clawsweeper Bot added P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Sep 12, 2026
@clawsweeper

clawsweeper Bot commented Sep 12, 2026

Copy link
Copy Markdown

Codex review: needs real behavior proof before merge. Reviewed September 12, 2026, 3:50 PM ET / 19:50 UTC.

ClawSweeper review

What this changes

The PR template asks contributors to describe the problem and user impact first, keep technical explanations brief, and summarize evidence and important risks visibly.

Merge readiness

⛔ Blocked before merge - 1 item remains

This is a useful, focused wording improvement that is not yet on main. No actionable correctness or security defect was found.

Priority: P3
Reviewed head: 56aee17c31d3d066c2c3d2eb55476529cc916808

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) Recorded reviewer rating: A focused editorial patch with preserved headings, clear scope, and no actionable findings. Real behavior proof remains required by host policy.
Proof confidence 🌊 off-meta tidepool Recorded reviewer rating; Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: This bot-authored template edit has no runtime path; the complete source and supplied PR description support the editorial assessment.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Required by policy Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: This bot-authored template edit has no runtime path; the complete source and supplied PR description support the editorial assessment.
Evidence reviewed 6 items Applicable repository policy: Read the complete root AGENTS.md; no nested policies or maintainer notes were found for the changed path. The template change does not trigger package, runtime, or crabpot smoke requirements.
Complete template and introduced change: Inspected the full template and pinned introduced patch: one file, 17 additions and 21 deletions. All four section names remain; the maintainer-edit requirement moves into the author-facing HTML comment. No executable configuration changes.
Main and release comparison: The fetched main revision, also tagged v0.3.25, retains the older wording and section order. The requested editorial update remains distinct.
Findings None None.
Security None None.

How this fits together

GitHub uses this template to seed new pull request descriptions. Its prompts guide contributors toward information reviewers need to understand the change and its validation.

flowchart LR
 A[Contributor opens PR] --> B[Description template]
 B --> C[Problem and user impact]
 B --> D[Rationale and evidence]
 C --> E[Maintainer review]
 D --> E
Loading

Before merge

  • Add real behavior proof - Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: This bot-authored template edit has no runtime path; the complete source and supplied PR description support the editorial assessment.
Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep a concise problem-first template with stable headings and visible summaries of impact, risks, required actions, and evidence.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this changes editorial guidance rather than repairing a runtime defect.

Is this the best way to solve the issue?

Yes: updating the existing template preserves its structure and avoids a competing contribution workflow.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 2e21b3b48aa0.

Labels

Label changes:

  • add P3: This is low-risk contributor documentation polish with no runtime or package behavior change.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. This is the recorded reviewer rating; real behavior proof remains required by host policy.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: This bot-authored template edit has no runtime path; the complete source and supplied PR description support the editorial assessment.

Label justifications:

  • P3: This is low-risk contributor documentation polish with no runtime or package behavior change.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. This is the recorded reviewer rating; real behavior proof remains required by host policy.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: This bot-authored template edit has no runtime path; the complete source and supplied PR description support the editorial assessment.

Evidence

What I checked:

  • Applicable repository policy: Read the complete root AGENTS.md; no nested policies or maintainer notes were found for the changed path. The template change does not trigger package, runtime, or crabpot smoke requirements. (AGENTS.md:1, 56aee17c31d3)
  • Complete template and introduced change: Inspected the full template and pinned introduced patch: one file, 17 additions and 21 deletions. All four section names remain; the maintainer-edit requirement moves into the author-facing HTML comment. No executable configuration changes. (.github/pull_request_template.md:17, 56aee17c31d3)
  • Main and release comparison: The fetched main revision, also tagged v0.3.25, retains the older wording and section order. The requested editorial update remains distinct. (.github/pull_request_template.md:28, 2e21b3b48aa0)
  • Prior template ownership: GitHub identifies hannesrudolph as author and merger of the earlier template alignment at chore: align pull request template #45. Local follow-history encountered an unavailable historical object; GitHub commit history and the commit patch supplied the relevant provenance. (.github/pull_request_template.md, cfe579503ee7)
  • Referenced editorial precedent: The PR explicitly carries over wording from docs: make PR descriptions plain-language first openclaw#146253, which GitHub confirms is merged. Its description preserves the four headings and prioritizes plain-language outcomes. This is editorial precedent, not a runtime dependency or a same-repository replacement.
  • Read-only validation: The pinned patch passes whitespace validation. The supplied PR description demonstrates the revised section order and concise outcome-first wording; runtime behavior is unchanged. (.github/pull_request_template.md, 56aee17c31d3)

Likely related people:

  • hannesrudolph: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score Internal tier Crab rank Meaning
6/6 S 🦀 challenger crab Exceptional readiness
5/6 A 🦞 diamond lobster Very strong readiness
4/6 B 🐚 platinum hermit Good normal PR; ordinary maintainer review
3/6 C 🦐 gold shrimp Useful, but confidence is limited
2/6 D 🦪 silver shellfish Proof or implementation needs work
1/6 F 🧂 unranked krab Not merge-ready
N/A NA 🌊 off-meta tidepool Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@hannesrudolph
hannesrudolph merged commit f36e5bb into main Sep 14, 2026
9 of 10 checks passed
@hannesrudolph
hannesrudolph deleted the docs/plain-english-pr-template branch September 14, 2026 23:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants