docs: add release notes style guide

This commit is contained in:
Misaka_Company
2026-03-24 17:44:48 +08:00
parent 2adfc77a58
commit 1d5268a4da

106
docs/releases/README.md Normal file
View File

@@ -0,0 +1,106 @@
# 发布文档规范
## 文档定位
发布文档面向**最终用户**,不是技术开发日志。内容应该简洁、清晰、有价值。
## 内容风格
### ✅ 推荐写法
- **用户视角**:描述功能带来的价值,而非技术实现
- **简洁明了**:每条更新 1-2 句话,避免冗长
- **分类清晰**:按功能模块或改进类型分组
**示例**
```markdown
## 核心功能
- 新增 Playwright 浏览器自动下载,首次启动自动从 S3 获取。
- 实时显示下载进度(百分比、速度、剩余时间)。
```
### ❌ 避免写法
- 技术细节(文件路径、代码实现、架构设计)
- 开发过程描述("重构了"、"优化了算法"
- 过长的段落(超过 2 行)
## 文档结构
### 标准格式
```markdown
# {版本号}
## {分类 1}
- {更新点 1}
- {更新点 2}
## {分类 2}
- {更新点 1}
- {更新点 2}
```
### 常见分类
- `核心功能` - 新功能、重大特性
- `改进` / `体验优化` - 现有功能优化
- `问题修复` - Bug 修复
- `界面与交互` - UI/UX 改进
## 篇幅要求
- **小版本**x.x.15-10 行
- **中版本**x.x.010-20 行
- **大版本**x.0.020-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 由发布脚本自动生成,不手动维护