Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs/steering/pr-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# PR Review Guide for openabdev/openab

## Review Framework

When reviewing a PR, always address these four questions:

1. **他解決什麼問題或需求** — 這個 PR 要解決什麼痛點或滿足什麼需求?用白話說明背景。
2. **他用什麼方式解決** — 具體的技術做法、架構設計、關鍵實作細節。
3. **他考慮過其他方式嗎** — 從 PR 描述、討論、commit history 中找出被考慮過但沒採用的替代方案,以及為什麼被否決。
4. **這是目前最好的方式嗎** — 評估現有做法是否最佳,指出可以改進的地方和潛在風險。

## Severity Levels

Use emoji + color to classify each review comment:

| Level | Emoji | Meaning | Action Required |
|-------|-------|---------|-----------------|
| 🔴 Critical | `## 🔴 Critical:` | Correctness bug, security issue, data loss risk | Must fix before merge |
| 🟡 Minor | `## 🟡 Minor:` | Style inconsistency, missing defense-in-depth, non-blocking improvement | Should fix, doesn't block merge |
| 🟢 Info | `## 🟢 Info:` | Knowledge sharing, future consideration, design tradeoff note | No action needed |

## Comment Format

Each review comment should include:

1. **What's wrong** — describe the issue clearly
2. **Where** — file path and line number
3. **Why it matters** — what breaks or what risk it introduces
4. **Fix** — provide a concrete code suggestion

### Example (from PR #210)

```
## 🔴 Critical: resize() distorts aspect ratio

**File:** `src/discord.rs`, line ~320

`image::Image::resize(w, h, filter)` resizes the image to the exact
given dimensions — it does not preserve aspect ratio automatically.
A 4000×2000 landscape image gets squashed into 1200×1200.

### Fix

​```rust
let ratio = f64::from(IMAGE_MAX_DIMENSION_PX) / f64::max(w, h);
let new_w = (f64::from(w) * ratio) as u32;
let new_h = (f64::from(h) * ratio) as u32;
img.resize(new_w, new_h, image::imageops::FilterType::Lanczos3)
​```
```

## Self-Review Checklist (before opening PR)

Authors should check these before requesting review:

- [ ] **API behavior verified** — read the docs for any new library/function used
- [ ] **Safety checks preserved** — if refactoring, confirm all original validation/security checks are still present
- [ ] **Code style consistent** — logging, error handling, naming match the existing codebase
- [ ] **Tests test the right thing** — assertions reflect actual expected behavior, not just "passes"

## Review Etiquette

- **Be specific** — "this is wrong" is not helpful; show what's wrong and how to fix it
- **Classify severity** — not everything is a blocker; use 🔴🟡🟢 so the author knows what to prioritize
- **Acknowledge good work** — if something is well done, say so
- **One round if possible** — batch all feedback in one review pass to avoid back-and-forth