107 lines
2.3 KiB
Markdown
107 lines
2.3 KiB
Markdown
# 发布文档规范
|
||
|
||
## 文档定位
|
||
|
||
发布文档面向**最终用户**，不是技术开发日志。内容应该简洁、清晰、有价值。
|
||
|
||
## 内容风格
|
||
|
||
### ✅ 推荐写法
|
||
|
||
- **用户视角**：描述功能带来的价值，而非技术实现
|
||
- **简洁明了**：每条更新 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 由发布脚本自动生成，不手动维护
|