docs: add release notes style guide
This commit is contained in:
106
docs/releases/README.md
Normal file
106
docs/releases/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# 发布文档规范
|
||||
|
||||
## 文档定位
|
||||
|
||||
发布文档面向**最终用户**,不是技术开发日志。内容应该简洁、清晰、有价值。
|
||||
|
||||
## 内容风格
|
||||
|
||||
### ✅ 推荐写法
|
||||
|
||||
- **用户视角**:描述功能带来的价值,而非技术实现
|
||||
- **简洁明了**:每条更新 1-2 句话,避免冗长
|
||||
- **分类清晰**:按功能模块或改进类型分组
|
||||
|
||||
**示例**:
|
||||
|
||||
```markdown
|
||||
## 核心功能
|
||||
|
||||
- 新增 Playwright 浏览器自动下载,首次启动自动从 S3 获取。
|
||||
- 实时显示下载进度(百分比、速度、剩余时间)。
|
||||
```
|
||||
|
||||
### ❌ 避免写法
|
||||
|
||||
- 技术细节(文件路径、代码实现、架构设计)
|
||||
- 开发过程描述("重构了"、"优化了算法")
|
||||
- 过长的段落(超过 2 行)
|
||||
|
||||
## 文档结构
|
||||
|
||||
### 标准格式
|
||||
|
||||
```markdown
|
||||
# {版本号}
|
||||
|
||||
## {分类 1}
|
||||
|
||||
- {更新点 1}
|
||||
- {更新点 2}
|
||||
|
||||
## {分类 2}
|
||||
|
||||
- {更新点 1}
|
||||
- {更新点 2}
|
||||
```
|
||||
|
||||
### 常见分类
|
||||
|
||||
- `核心功能` - 新功能、重大特性
|
||||
- `改进` / `体验优化` - 现有功能优化
|
||||
- `问题修复` - Bug 修复
|
||||
- `界面与交互` - UI/UX 改进
|
||||
|
||||
## 篇幅要求
|
||||
|
||||
- **小版本**(x.x.1):5-10 行
|
||||
- **中版本**(x.x.0):10-20 行
|
||||
- **大版本**(x.0.0):20-40 行
|
||||
|
||||
## 示例参考
|
||||
|
||||
### 简洁版(1.4.2)
|
||||
|
||||
```markdown
|
||||
# 1.4.2
|
||||
|
||||
## 架构优化
|
||||
|
||||
- 重构主进程启动流程和 IPC 编排层,按领域拆分 preload API。
|
||||
- 解耦更新服务职责,对话框改为懒加载以优化性能。
|
||||
|
||||
## 质量改进
|
||||
|
||||
- 修复类型检查问题,加固启动流程和认证健壮性。
|
||||
- 新增核心模块测试覆盖,完善开发者文档。
|
||||
```
|
||||
|
||||
### 详细版(1.4.0)
|
||||
|
||||
```markdown
|
||||
# 1.4.0
|
||||
|
||||
## 亮点
|
||||
|
||||
- 新增 Windows 便携版自动更新能力,支持 `stable` / `preview` 双通道发布。
|
||||
- 更新策略与登录用户角色联动。
|
||||
|
||||
## 自动更新
|
||||
|
||||
- 新增便携版更新服务,支持登录后自动检查更新。
|
||||
- 更新器采用原生 `portable-updater.exe`,不再依赖 PowerShell 脚本。
|
||||
```
|
||||
|
||||
## 发布流程
|
||||
|
||||
1. 创建版本文件:`docs/releases/{version}.md`
|
||||
2. 参考现有文档风格编写
|
||||
3. 提交 git:`git add docs/releases/{version}.md`
|
||||
4. 提交信息:`docs: add release notes for version {version}`
|
||||
|
||||
## 维护说明
|
||||
|
||||
- 发布文档一旦创建,**不再修改**(除非有重大错误)
|
||||
- 技术细节放入 `docs/` 下的专题文档
|
||||
- Changelog 由发布脚本自动生成,不手动维护
|
||||
Reference in New Issue
Block a user