π OpenHands: AI-Driven Development
docs(codereview): require design docs for deep, high-risk PRs (#17267)
πΎ smolpawsbb24c705572f
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.mdindex 8d7760d77c..3e13cbece5 100644--- a/.agents/skills/custom-codereview-guide.md+++ b/.agents/skills/custom-codereview-guide.md@@ -184,6 +184,51 @@ data, user actions, lazy initialization, store mirroring, or ordering repairs.Subscriptions, browser APIs, timers, and network synchronization remain validwhen cleanup and dependencies are explicit.+## Design Context for Deep PRs++A diff shows each changed line, not the design. Expect durable design context+when a reviewer cannot judge a PR from the diff in a couple of minutes, for+example:++- a new or changed Agent Server, Cloud, or automation integration, event+ contract, or persisted-state shape;+- a new feature module or subsystem, a cross-cutting refactor, or a migration;+- a behavior change in backend selection, conversation flow, or settings and+ profile transitions; or+- a large change whose intent cannot be reconstructed from the diff, even if no+ single hunk is complex.++Do not ask for design context on trivial, generated, or self-explanatory+changes: a typo, a one-line guard, a dependency bump, a copy or style tweak, or a+small localized fix. Size alone does not make a PR deep.++Adequate design context states:++- **Intent:** the problem and why this approach;+- **Before and after:** the important behavior, UI flow, or API shape on each+ side;+- **Compatibility and risk:** affected Canvas modes, stored state, and supported+ backends, and what can break; and+- **Code references:** links to the real code at a commit SHA.++Put it in the PR description, or link a `.pr/` design doc that covers it from+the `pr-design-doc` skill. Count a `.pr/` doc only when the link is pinned to a+commit SHA, not the branch name. Approving a same-repository PR runs the+`PR Artifacts` cleanup, which removes `.pr/` from the branch, so a branch link+stops resolving before a human maintainer reads it, while a SHA link keeps+working.++Scale the response to the risk assessment:++- **Deep and π΄ HIGH risk without adequate context:** submit **COMMENT** and ask+ for the write-up or a SHA-pinned doc.+- **Deep and π‘ MEDIUM risk:** ask for it when the change is hard to reconstruct+ from the diff; a small, self-evident change does not need it.+- **π’ LOW risk:** never withhold approval for missing design context.++Design context is a review aid, not a merge gate by itself. It does not excuse a+correctness, security, compatibility, or architecture defect.+## Dependencies and Releases- Direct dependencies are exact-pinned. Update `package.json` anddiff --git a/.agents/skills/pr-design-doc/SKILL.md b/.agents/skills/pr-design-doc/SKILL.mdindex 62f02c6a67..e5ef5066b0 100644--- a/.agents/skills/pr-design-doc/SKILL.md+++ b/.agents/skills/pr-design-doc/SKILL.md@@ -48,8 +48,10 @@ cleanup, verify that the target repository has an enabled- Fork PR, or repository without a verified cleanup workflow: remove `.pr/` manually beforemerge.-The design doc is a review aid that lives with the branch while the PR is open. It must not-ship in the merged tree.+The design doc is a temporary review aid and must not ship in the merged tree. Automated+approval can trigger cleanup before human review. Keep the essential design summary in the+PR description: intent, important before/after behavior or API shape, compatibility, risk,+and code references. Use commit-pinned document links so cleanup does not break access.## Workflow@@ -102,17 +104,21 @@ ship in the merged tree.git add .pr/design.htmlgit commit -m "docs(.pr): design doc for <PR topic>"git push <head-repo-remote> HEAD:<headRefName>+ git rev-parse HEAD```- Query the base repository's visibility before choosing the link:+ Use the resulting full SHA as `<doc-commit-sha>` in document links. Refresh the document+ and its link when substantive changes affect the design; a cleanup-only commit does not+ need a new link. Query the base repository's visibility before choosing the link:```bashgh repo view <base-owner>/<base-repo> --json visibility,url```- **Public repository:** add an htmlpreview link near the top of the PR description,- pointing at the **fork and branch the PR is opened from** (it renders before merge):+ pointing at the **PR head repository and commit containing the document**:```- π Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html+ π Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<doc-commit-sha>/.pr/design.html```- - **Private or internal repository:** link the access-controlled GitHub blob and include+ - **Private or internal repository:** link the access-controlled GitHub blob at the same+ document commit and includelocal download/open instructions, or use an existing access-controlled artifactservice. Never send the document through htmlpreview or another public host.diff --git a/.agents/skills/pr-design-doc/references/html-craft.md b/.agents/skills/pr-design-doc/references/html-craft.mdindex 974a9c6490..58cf8c4d84 100644--- a/.agents/skills/pr-design-doc/references/html-craft.md+++ b/.agents/skills/pr-design-doc/references/html-craft.md@@ -290,16 +290,18 @@ directory, then build the link and paste it in the PR description:```bash# commit the html under .pr/ on your PR branch (this dir is temporary, see the skill)git add .pr/design.html && git commit -m "docs(.pr): design doc" && git push <your-fork> <branch>-# link template - use YOUR fork + PR branch, so it renders before the PR is merged:-# https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html+# use the full SHA of the pushed document commit in the link:+git rev-parse HEAD+# https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<doc-commit-sha>/.pr/design.html```Example shape:-`https://htmlpreview.github.io/?https://github.com/FORK_OWNER/REPO/blob/PR_BRANCH/.pr/design.html`+`https://htmlpreview.github.io/?https://github.com/FORK_OWNER/REPO/blob/DOC_COMMIT_SHA/.pr/design.html`-`<pr-branch>` can be any branch or commit - `raw.githubusercontent.com` serves it regardless-of merge state, so the doc renders while the PR is still open. Point the URL at the **fork-and branch the PR is opened from**, not `main`.+Point the URL at the **PR head repository and full commit SHA containing the document**.+A branch-based link breaks when `.pr/` is removed after approval; a commit-pinned link+continues to reference the document before cleanup. Refresh the document and its link when+substantive changes affect the design.For public repositories, anyone can open the rendered page without a download or local server.This works with self-contained pages containing only inline CSS and SVG.@@ -310,8 +312,9 @@ This works with self-contained pages containing only inline CSS and SVG.the design doc to GitHub Pages or another public host. Keep the document free of externalscripts and assets: opening a local file does not make third-party active content private.-- Link authorized reviewers to the committed GitHub blob and ask them to download and open the- self-contained HTML file locally; or use an existing access-controlled artifact service.+- Link authorized reviewers to the GitHub blob at the full document commit SHA and ask them to+ download and open the self-contained HTML file locally; or use an existing access-controlled+ artifact service.- For a local browser preview, open `.pr/design.html` directly. If the browser needs HTTP,serve only on loopback:```bash