Skip to content

docs: help reviewers understand OCM changes - #1014

Merged
roboclaw-bot merged 4 commits into
mainfrom
openclaw/pr-template-rollout-ocm
Nov 17, 2026
Merged

roboclaw-bot merged 4 commits into
mainfrom
openclaw/pr-template-rollout-ocm

Conversation

@roboclaw-bot

@roboclaw-bot roboclaw-bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

What Problem This Solves

OCM pull requests can name implementation details without explaining the operator task or what validation actually demonstrated, making changes harder to assess without reading the code.

User Impact

Contributors get OCM-specific examples for explaining the problem and outcome, while reviewers see the observed result before command lists. There is no change to OCM behavior, required checks, security policy, or operator actions.

Why This Change Was Made

Refine the existing author-facing comments instead of adding another template or review gate. The four headings, maintainer-edit requirement, exact problem prompt, and existing impact/rationale guidance remain unchanged. TLS connection-URL examples use OCM’s documented service-status workflow.

Evidence

The candidate preserves every byte outside HTML comments, including all four headings, while making the title/problem examples and evidence instructions reader-first. Remote validation passed and independent read-only review found no actionable issues.

  • The TLS example agrees with the service-status documentation; repository template consumers and CI guidance were reviewed.
  • Followed the existing Markdown-prose-only path in CONTRIBUTING.md: remote whitespace check plus source/CI parity. No shell recipe or executable input changes; Rust, packaging and lifecycle suites were not run locally or on the disposable worker. Hosted CI remains separate.
  • GitHub saved this completed template-based description, and authoritative readback confirmed its four sections, contributor credit and exact work-session links. This is explicit authoring/save proof, not automatic browser-prefill proof.
  • The final published head contains only the template change. Its complete tree matches the remotely tested candidate, so that proof remains applicable after removing inadvertently included working artifacts.
Remote verification and source identity

An owned AWS Linux worker received the exact Git bundle and patch.

Base: 6879db78f36bd86adfe2f6dec860d2b8520aa8d2
Remotely tested candidate: bdb8366665999c644abc5023beb5466908ee0c2d
Published head: b33d0abea622655e306fd0c0e2ffbc565260f78c
Identical complete tree: 415347c605df8d04adf00b41090a79286c957435
Patch blob: 9b018aaa4fd98ac2911c62ee88be6655afba1863
Cargo.lock blob (unchanged): e65ce614f7367356f9b4bd8127b316dc2197fcff
Template blob: 7ed808961706510c127820718f5818d62bfec303
Linux 7.0.0-1014-aws x86_64; Git 2.53.0; Python 3.14.4
git diff --check HEAD: PASS
Structural assertions: PASS

Assertions compare all noncomment bytes, heading order, the exact problem sentence, maintainer-edit instructions, unchanged impact/rationale guidance and checklist parity (none in either version); only .github/pull_request_template.md changes.

Requested by and co-authored with @hannesrudolph.

Work sessions

Linked for team reference; these sessions aren’t public.

Worked on by

roboclaw-bot and others added 2 commits November 17, 2026 01:53
Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
Worked on by:
- @hannesrudolph

Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
OpenClaw-Publication: c997eed7-0f3e-4e30-a0ca-f671aa38bdcc
@clawsweeper

clawsweeper Bot commented Nov 17, 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 and others added 2 commits November 17, 2026 01:55
Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
Worked on by:
- @hannesrudolph

Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
OpenClaw-Publication: aafe70d8-00d6-4448-91c5-5ce1be881a51
@clawsweeper clawsweeper Bot added clawsweeper:intake:docs Preliminary submission classification; full source review pending. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed clawsweeper:intake:docs Preliminary submission classification; full source review pending. labels Nov 17, 2026
@clawsweeper

clawsweeper Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codex review: needs maintainer review before merge.

What this changes

This PR updates author-facing template comments with OCM-specific examples and guidance to explain validation results before listing commands.

Example: A contributor describes a correction to TLS connection URLs.

  • Before: The template uses generic task-list examples.
  • After: The template suggests “fix: show the correct connection URL for TLS-enabled environments.”

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) Useful, narrowly scoped documentation with appropriate source checks and no actionable defects; CI completion remains separate from patch correctness.
Proof confidence 🐚 platinum hermit (4/6) Documentation-only guidance needs no runtime proof; the body supplies remote prose validation and explicit authoring/save evidence, and source inspection confirms its OCM example.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Contributors can describe implementation details and command lists without making the operator problem or observed result clear to reviewers.
Reason: The maintainer-authored direction extends the established template approach with concrete OCM examples and no additional review gate.

Merge readiness

✅ Ready for maintainer review

Keep open: this is a useful, focused template improvement absent from main, with no actionable patch defects found; the failed signed-binary CI check still needs resolution.

Priority: P3
Reviewed head: b33d0abea622655e306fd0c0e2ffbc565260f78c

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub's repository PR template supplies contributor instructions and section headings that become the starting point for descriptions reviewers read.

flowchart LR
  A[Repository template] --> B[Contributor authors description]
  B --> C[GitHub saves PR body]
  C --> D[Reviewer assesses problem and evidence]
Loading

Technical review

Best possible solution:

Land the focused comment changes once the existing CI gate is satisfied.

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

No runtime bug is claimed; the existing generic examples and revised authoring guidance are directly inspectable in the pinned diff.

Is this the best way to solve the issue?

Editing the existing template comments is a proportionate solution that preserves the established review structure and required checks.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 6879db78f36b.

Provenance checked

Security

None.

Evidence

What I checked:

  • Introduced change and current main: The pinned diff changes only HTML comments in the existing template; the four visible headings, maintainer-edit reminder, and impact/rationale guidance remain intact. GitHub still reports main at the pinned base. (.github/pull_request_template.md:6, b33d0abea622)
  • Repository policy and documentation validation: Read the complete root AGENTS.md and CONTRIBUTING.md; no nested .github policy, maintainer notes, or pr-simplify skill exists. CONTRIBUTING permits remote whitespace and source/link parity review for Markdown prose changes without new runtime exercises. (CONTRIBUTING.md:112, b33d0abea622)
  • Existing intent and feature history: The template was introduced in c4365f1 and revised toward plain-language descriptions by docs: make PR descriptions plain-language first #224; this PR continues that direction. The older template-creation blob and both relevant patches were readable, although git log --follow encountered an unavailable historical object. (.github/pull_request_template.md:27, 611e65b9c15b)
  • OCM example matches the documented workflow: Service-status documentation explicitly describes https URLs for TLS-enabled Gateways; the CLI calls status_with_gateway_url for formatted status, with matching existing TLS fixture assertions. (docs/USAGE.md:743, 6879db78f36b)
  • Supplied validation and discussion: Read the full live body, comments, reviews, and timeline. The body reports remote Markdown validation and explicit GitHub authoring/save readback, without claiming automatic browser prefill. The published head and reported tested candidate have identical complete trees. Optional team-session links satisfy the supplied provenance exception. (.github/pull_request_template.md:1, b33d0abea622)
  • CI attribution remains unresolved: The npm packaging test step passed, but “Prove signed native byte preservation through npm” failed in https://github.com/openclaw/ocm/actions/runs/43999238581/job/133758973480. Annotations provide only exit code 1; downloading logs was blocked by the proxy's Azure-host allowlist. Main's CI run https://github.com/openclaw/ocm/actions/runs/43576245056 passed, so an outside cause is not established and no diff-caused failure is asserted. (.github/workflows/ci.yml:287, b33d0abea622)

Likely related people:

  • Hannes Rudolph: Raw commit c4365f1 adds .github/pull_request_template.md:26 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: c4365f11c3c7; files: .github/pull_request_template.md)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

  • add P3: Contributor documentation polish improves review clarity without changing runtime behavior or automation.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

  • P3: Contributor documentation polish improves review clarity without changing runtime behavior or automation.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 16, 2026, 9:11 PM ET / November 17, 2026, 02:11 UTC.

@roboclaw-bot
roboclaw-bot merged commit 96b1032 into main Nov 17, 2026
22 of 23 checks passed
@roboclaw-bot
roboclaw-bot deleted the openclaw/pr-template-rollout-ocm branch November 17, 2026 02:41
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: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant