Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: encourage .pr/ HTML design doc + htmlpreview link for non-trivial PRs (#16316)

🐾 smolpawsb3a3ed3100d1
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 3cc55df8b1..e4d00e78e3 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -12,7 +12,7 @@ AGENT:
Do not edit the HUMAN section.
Write a concise summary of what changed and link any reviewer artifacts, such
as files under `.pr/`. For HTML artifacts, include a rendered preview link:
-https://htmlpreview.github.io/?https://github.com/<owner>/<repo>/blob/<branch>/.pr/<file>.html
+https://htmlpreview.github.io/?https://github.com/<owner>/<repo>/blob/<commit-sha>/.pr/<file>.html
In this AGENT section and the template fields below, provide evidence that the
code runs properly end-to-end. Just running unit tests is NOT sufficient. Explain
exactly what command you ran and include logs, screenshots, or reproduction notes.
@@ -52,6 +52,20 @@ error state) and then the result after your fix. A terminal screenshot or video
is fine for non-UI bugs.
-->
+## Design Doc
+
+<!--
+Optional, encouraged for non-trivial PRs. Add a self-contained HTML design doc under the
+temporary `.pr/` directory (e.g. `.pr/design.html`) covering the code/API design and a
+before/after of your change, then link it here via htmlpreview at the commit that contains it:
+
+ https://htmlpreview.github.io/?https://github.com/<your-fork>/<repo>/blob/<commit-sha>/.pr/design.html
+
+Use the commit SHA, not the branch name: `.pr/` is removed from the branch when a
+same-repository PR is approved, and a branch link stops working then.
+See docs/DEVELOPMENT.md ("Design doc for non-trivial PRs") for details.
+-->
+
## Type
- [ ] Bug fix
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 2bd2afc8f1..1190bc2ece 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -355,6 +355,43 @@ threshold.
Stryker does not cover the small Python surface in this repository; mutating it
would need a Python test harness and Python-specific mutation tool.
+## Design doc for non-trivial PRs
+
+For a non-trivial PR β€” a new or changed public API, a new subsystem, a behavior change in
+core logic, or a migration β€” a reviewer often has to reconstruct the design from the diff
+alone. That is slow. You are encouraged (not required) to add a short design doc so reviewers
+grasp the proposal at a glance.
+
+The convention:
+
+1. Write a **self-contained HTML** page (inline CSS/SVG, opens by double-click) that covers
+ the code/API design and a **before/after** of your change, grounded to the actual code.
+ Keep it static, with no scripts: htmlpreview runs the page in the reviewer's browser.
+2. Commit it under the temporary **`.pr/`** directory, e.g. `.pr/design.html`. This directory
+ is for PR-only artifacts and must not land in `main`. For a same-repository PR it is
+ **removed automatically when the PR is approved** (`.github/workflows/pr-artifacts.yml`).
+ For a fork PR the workflow cannot push to your branch; it posts a notice and, if `.pr/`
+ reaches `main` after merge, opens or updates a cleanup PR. Delete `.pr/` yourself before merge.
+3. Link it near the top of the PR description via htmlpreview, at the commit that contains
+ the page (`git rev-parse HEAD` after you push it):
+
+ ```
+ https://htmlpreview.github.io/?https://github.com/<your-fork>/<repo>/blob/<commit-sha>/.pr/design.html
+ ```
+
+ Use the commit SHA, not the branch name. Approval cleanup removes `.pr/` from the branch,
+ so a branch link stops working while a SHA link keeps resolving. Refresh the link when the
+ page changes substantively.
+
+Keep the essentials in the PR description as well: the intent, the important before/after
+behavior or API shape, compatibility and risk, and code references. The page adds detail.
+
+Skip this for trivial PRs (a typo, a one-line guard, a dependency bump) β€” there, a design doc
+is just noise. htmlpreview only works for public repos and self-contained pages.
+
+The [`pr-design-doc`](../.agents/skills/pr-design-doc/SKILL.md) skill can generate the page
+for you.
+
## CSS isolation and host-app customization
The standalone app and the exported provider/root wrapper now scope all bundled CSS under a dedicated shell element with the `data-agent-server-ui` attribute. That means Tailwind utilities, HeroUI component styles, xterm styles, and local CSS only apply inside the OpenHands UI subtree instead of leaking into a host app.