Skip to content

docs: help readers understand crawlkit pull requests - #254

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

roboclaw-bot merged 2 commits into
mainfrom
openclaw/pr-template-rollout-crawlkit

Conversation

@roboclaw-bot

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

Copy link
Copy Markdown
Contributor

What Problem This Solves

A crawlkit PR can describe parser or database internals without explaining what an operator or crawl-app developer is trying to do, what goes wrong, or why it matters. Readers then have to inspect the diff to understand its purpose.

User Impact

PR authors get crawlkit-specific examples of clear titles and problem statements, with validation summaries that explain the checked behavior and result before commands or logs. There is no runtime change and no new required section, checklist, test, or review gate.

Why This Change Was Made

Adapt the reader-first guidance to supported crawlkit workflows: running refresh jobs whose names resemble flags and stopping database-write waits at their deadline. For example, prefer “let crawlctl run jobs whose names look like flags” over “guard parsing after the argument separator.” These are writing examples, not new fixes in this PR.

Only HTML comments in .github/pull_request_template.md change. Existing headings, visible template bytes, maintainer-edit guidance, risks and migration guidance, and the literal problem prompt remain unchanged.

Evidence

  • Structural checks passed: only the template changes; noncomment bytes and headings are identical; the required problem sentence and existing guidance are preserved.
  • Repository validation passed, including module tidiness, formatting, vet, dead-code and vulnerability analysis, unit and race tests, and all 47 script tests.
  • Independent read-only native review found no actionable P0–P3 issues and checked the examples against the README, parser and store tests.
  • No provider services, live app stores, release operations, or runtime behavior changes were involved. Hosted CI is tracked separately after publication.
Validation details

Reviewed base: b9fbd520a50528d920b65fe35a6229d165ce4611.
Reviewed candidate: 4c3a45c260eb3e09817815b23539bf487a599e38.
Candidate tree: 513a0dae7c347b19e71bccb4312ae36f7bb039cb.

  • GOWORK=off go vet ./... and GOWORK=off go test -count=1 ./...: passed with Go 1.27.4.
  • make check: passed in a clean detached worktree of the same candidate, including go mod tidy with unchanged go.mod/go.sum, formatting, vet, dead-code analysis, govulncheck (“No vulnerabilities found”), unit/race tests, and Node script tests (47 passed, 0 failed).
  • git diff --check and comment-preservation assertions: passed.
  • The initial full-check attempt traversed task-local downloaded Go fixtures during formatting; the unchanged candidate passed after isolating validation from those scratch inputs. No repository check or ignore rule was changed.

Worked on by

Work sessions

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

roboclaw-bot and others added 2 commits November 17, 2026 01:56
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: 72c428f3-73ce-4a4a-bab5-2daa7caf05df
@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.

@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 adds crawlkit-specific examples and clearer writing guidance to the pull request template’s HTML comments.

Example: An author describes a fix for refresh job names that resemble flags.

  • Before: The template illustrates titles with unrelated authentication and task-list examples.
  • After: The template suggests “fix: let crawlctl run jobs whose names look like flags.”

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) A useful, narrowly scoped documentation change with supported examples and no identified defect.
Proof confidence 🌊 off-meta tidepool Not applicable: This documentation-only change needs no shipped runtime demonstration; the template diff and referenced workflows were inspected directly.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Readers must inspect implementation details when a PR description does not explain the affected workflow and outcome.
Reason: The maintainer-authored direction builds on established template intent with relevant examples and no additional review gate.

Merge readiness

✅ Ready for maintainer review

This PR is a focused documentation improvement that is not on main. The examples match supported workflows, existing review guidance is preserved, and no actionable defects were found.

Priority: P3
Reviewed head: c7fe8d8ad769cea7c75101d4157de997d0d59877

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub presents the repository’s Markdown template to PR authors; its comments guide authoring while the four headings structure the published description.

flowchart LR
  A[Repository template] --> B[GitHub PR editor]
  B --> C[Author reads guidance]
  C --> D[PR description]
  D --> E[Maintainer review]
Loading

Technical review

Best possible solution:

Land the focused template guidance while preserving its existing sections and substantive review requirements.

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

No runtime bug is claimed; source inspection confirms the writing examples describe supported crawlkit workflows.

Is this the best way to solve the issue?

Editing the existing template comments is a small, appropriate way to improve descriptions without adding sections, checks, or runtime machinery.

AGENTS.md: found and applied where relevant.

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

Provenance checked

  • PR title examples and common structure keeps the original intent (cd14c9e: Standardize how PRs explain problems, rationale, user impact, and evidence.)
  • Problem and evidence authoring guidance keeps the original intent (14df981: Lead with plain-language problems and outcomes while preserving risks, migrations, evidence, and maintainer-edit guidance.)

Security

None.

Evidence

What I checked:

  • Pinned diff, supported examples, and prior intent: The introduced diff changes only HTML comments in the template, retaining visible content, headings, risk and migration guidance, and maintainer-edit guidance. README.md documents literal job names after -- and deadline-aware SQLite waits; parser code and cancellation tests support those examples. Earlier template work in chore: align pull request template #55 and docs: make PR descriptions plain-language first #121 established consistent structure and plain-language descriptions. Current-head checks report seven successes and one skipped downstream-app check. The candidate named in the body and the reviewed head have identical trees. Root AGENTS.md was read; no .github/AGENTS.md, maintainer notes, or pr-simplify skill exists. Follow-history traversal encountered one unavailable old object; path history and supplied provenance cover both earlier template changes. (.github/pull_request_template.md:6, c7fe8d8ad769)

Likely related people:

  • Hannes Rudolph: Raw commit cd14c9e adds .github/pull_request_template.md:3 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: cd14c9ebc1c4; files: .github/pull_request_template.md)
  • RoboClaw: Raw commit 14df981 adds .github/pull_request_template.md:34 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 14df981aa46a; 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: This is low-risk contributor documentation polish with no runtime or automation changes.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool 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: This is low-risk contributor documentation polish with no runtime or automation changes.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool 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:12 PM ET / November 17, 2026, 02:12 UTC.

@roboclaw-bot
roboclaw-bot merged commit d851f55 into main Nov 17, 2026
8 checks passed
@roboclaw-bot
roboclaw-bot deleted the openclaw/pr-template-rollout-crawlkit branch November 17, 2026 02:32
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