写出好的 PR 和 README

为什么技术写作很重要

代码审查中，你的 PR 描述是审查者的入口点。好的 PR 描述能：

✅ 让审查者快速理解你做了什么
✅ 减少来回的问题
✅ 显得你思考周密
✅ 在 3 个月后你查阅历史时，节省你的时间

同样，好的 README 能：

✅ 让新人快速上手
✅ 减少重复的问题
✅ 显得项目专业

PR 描述的标准结构：What/Why/How/Testing

1. What（做了什么）

简洁总结，一句话。

Refactor authentication flow to support OAuth2 and magic link sign-up

或更详细的版本：

What: Refactor authentication flow to support OAuth2 and magic link sign-up

This PR replaces the old session-based auth with a stateless JWT approach,
enabling OAuth2 for easy sign-in and magic link for passwordless access.

关键表达：

Add X — 新增功能
Fix X — 修复 bug
Refactor X — 重写代码（不改功能）
Optimize X — 改进性能
Implement X — 实现某个设计

2. Why（为什么做）

这是最常被忽略的部分。说明背景和动机。

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

或故事式：

Why:
Recently, we had three enterprise customers request OAuth2 support
for their SSO integration. Our current session-based auth can't handle
cross-domain SSO, so we're migrating to JWT + OAuth2.

好的 Why 的标志：

✅ 提到了业务理由（用户需求、性能、可维护性）
✅ 解释了为什么现有方案不够
✅ 说明了为什么这个解决方案更好

3. How（怎么做的）

技术实现的高层概览。不需要逐行解释（那是代码审查的工作），但需要让审查者知道整体架构。

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims
5. Added magic link generation and validation

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

关键表达：

Created X using Y — 技术选择
Replaced X with Y — 迁移
Added X routes — 新的 API 端点
Migrated X from Y to Z — 数据迁移
Breaking changes — 向后不兼容的改变

4. Testing（怎么测的）

说明你如何验证这个改变是对的。

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Verified JWT expiration and refresh flow works correctly
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)
- Tested on staging environment with real data

Outstanding:
- QA will do full regression testing (scheduled for Thursday)
- Performance benchmarks vs old auth (will share results in comment)

PR 描述的模板

复制这个，填空即可：

## What
[一句话总结]

[更详细的描述，2～3 句]

## Why
- [原因 1]
- [原因 2]
- [原因 3，如果有]

## How
1. [改变 1]
2. [改变 2]
3. [改变 3]

[如果有 breaking changes，在此说明]

## Testing
- [你做了什么测试]
- [结果是什么]
- [未完成的部分（如果有）]

## Related
Closes #123
Depends on #456 (wait for this to merge first)

README 的常见结构

开头：项目是什么

# ProjectName

One-sentence description of what this project does.

[一个 demo gif 或截图]

例子：

# DevLingo

A macOS menu bar app that helps non-native English speaking developers
improve their English in the flow of work. Select text → global hotkey →
learn pronunciation, synonyms, grammar tips.

安装（Getting Started）

## Getting Started

### Prerequisites
- macOS 12+
- Node.js 18+ (for backend development)
- Xcode 14+ (for macOS app development)

### Installation
1. Clone the repository
2. Follow setup instructions in `/backend` and `/MacApp`
3. Run `npm run dev` in backend folder
4. Open `MacApp/DevLingo.xcodeproj` in Xcode

使用（Usage）

## Usage

### Basic Usage
1. Select any English text
2. Press ⌘⇧D (global hotkey)
3. Learn pronunciation, examples, synonyms

### Advanced Features
- Save words to personal vocabulary
- Spaced repetition for review
- Batch import from CSV

贡献（Contributing）

## Contributing

We welcome contributions! Here's how to help:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-thing`)
3. Commit your changes
4. Push to branch and create a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

技术写作的语法陷阱

1. 时态（最常见的错误）

原则：现在式表达代码做什么，过去式表达你做了什么改变

错误	原因	正确
”The function was created to handle X”	听起来像历史叙述	”The function handles X” 或 “This PR adds a function that handles X"
"The code will validate input”	太不确定	”The code validates input"
"We added the feature” (在 README)	README 不讲历史	”This feature allows users to…“

2. 冠词（中文使用者常见错误）

原则：第一次提到用 “a/an”，后续用 “the”；或用复数避免冠词

错误	原因	正确
”We refactored authentication flow”	听不清是哪个 flow	”We refactored the authentication flow” 或 “We refactored authentication flows"
"Function handles case when user logs in”	中文式，缺 “the"	"The function handles the case when a user logs in”

3. 被动语态过度

原则：英文更倾向主动。除非你不想说是谁做的，否则用主动

被动（常见中文干扰）	主动（更好）
“The JWT is generated by the server"	"The server generates the JWT"
"The user data is stored in D1"	"We store user data in D1"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. 同义词的微妙区别

词汇	用法
Add	新增功能（完全不存在）:“Add OAuth2 support”
Implement	实现一个已知的设计：“Implement the design from #123”
Create	生成一个新对象：“Create JWT service”
Build	构建系统:“Build the CI/CD pipeline”
Refactor	改进现有代码，不改功能:“Refactor auth middleware”
Optimize	提升性能:“Optimize query performance”
Fix	修复 bug:“Fix race condition in cache”

Express 模式用于审查你自己的 PR 描述

写完 PR 描述后，用 DevGlish Express 模式检查一遍：

例子：检查你的 Why 部分

你写的：

Why: Users need to sign up faster

粘贴到 Express 模式：

Input: "Users need to sign up faster"

Basic (Direct):
  "Users need to sign up faster"

Intermediate (Natural):
  "Users are requesting a faster sign-up process"

Native (Idiomatic):
  "We've had 5 sign-up requests from enterprise customers.
   The current form takes 3+ minutes. A passwordless option
   would significantly improve conversion."
  💡 Tip: 用数据和上下文而不是模糊的 "need"

选择「Native」并调整：

Why: We've received multiple requests from enterprise customers for
passwordless sign-up. Current form takes 3+ minutes and users often
abandon. Magic link sign-up would improve conversion and reduce support load.

README 的段落模式检查

用 DevGlish 的「段落模式」来审查你的 README 初稿：

DevGlish → Paragraph Mode
Input your README introduction

系统会标注：

句子结构（太复杂吗？）
重复的词（有更好的同义词吗？）
被动语态过度
不必要的词汇

PR 描述的快速清单

发送 PR 前，检查：

What 部分清楚说明了改变
Why 部分有商业或技术理由（不只是”想这样做”）
How 部分说了高层设计，审查者不用逐行读代码
Testing 部分说了你的测试覆盖
没有过度的被动语态
冠词用对了（“the” vs “a”）
时态一致（现在式说代码功能，过去式说改变）
链接到相关 issue（如果有）

README 的快速清单

开头一句话说清楚项目是什么
有 demo 或截图
安装步骤清晰、可复现
用法示例可以直接复制
有 contributing 指南（如果接受外部贡献）
有 license
语言简洁（不要太学术或太随意）