RailWise KB已发布
RAILWISE-CLI 更新日志模板与规范
CLI产品更新日志的标准化模板、撰写规范与发布流程，确保版本变更信息清晰、一致、可追溯
community-guide
RAILWISE-CLI 更新日志模板与规范
Section titled “RAILWISE-CLI 更新日志模板与规范”文档说明：本文档定义 RAILWISE-CLI 更新日志（Changelog）的标准格式、撰写规范与发布流程。所有 CLI 版本发布必须遵循本模板，确保用户能够快速了解版本变更内容。 适用范围：CLI 产品团队、技术文档团队、版本发布负责人
1. 版本命名规则
Section titled “1. 版本命名规则”RAILWISE-CLI 采用 语义化版本控制（Semantic Versioning 2.0.0）：
版本号格式：MAJOR.MINOR.PATCH[-prerelease][+build]
示例： v1.2.3 — 正式版本 v1.3.0-beta.1 — 预发布版本 v1.3.0+20250708 — 带构建元数据的版本| 版本段 | 说明 | 升级影响 |
|---|---|---|
| MAJOR | 重大架构变更、不兼容 API 修改 | 需迁移适配 |
| MINOR | 新增功能、向后兼容的 API 扩展 | 平滑升级 |
| PATCH | Bug 修复、安全补丁、性能优化 | 直接替换 |
| prerelease | 预发布标识（alpha/beta/rc） | 不建议生产环境使用 |
2. 更新日志模板
Section titled “2. 更新日志模板”2.1 标准模板结构
Section titled “2.1 标准模板结构”---title: "RAILWISE-CLI v{版本号} 更新日志"description: "CLI {版本号} 版本的新增功能、改进项、修复项与兼容性说明"category_primary: "产品文档"category_secondary: "版本更新"tags: ["cli", "changelog", "v{版本号}"]author: "RailWise CLI团队"date: "{发布日期}"version: "{版本号}"---
# RAILWISE-CLI v{版本号} 更新日志
> **发布日期**：{YYYY-MM-DD}> **版本状态**：{活跃维护/维护中/已停止}> **下载地址**：https://railwise.cn/download/cli/v{版本号}> **Docker 镜像**：railwise/cli:{版本号}
---
## 新增功能
| 功能 | 说明 | 适用场景 | 相关命令/配置 ||------|------|---------|-------------|| **功能名称** | 功能描述 | 适用场景 | `railwise command` |
## 改进项
- 改进描述（量化指标优先）
## 修复项
- 修复描述（关联 Issue 编号）
## 破坏性变更
> ⚠️ 以下变更可能需要用户调整现有配置或脚本
| 变更项 | 影响范围 | 迁移方案 ||--------|----------|----------|| 变更描述 | 受影响的功能/命令 | 迁移步骤 |
## 兼容性
| 项目 | 要求 ||------|------|| Bun 运行时 | ≥ {最低版本} || 操作系统 | macOS {版本} / Windows {版本} / Linux {版本} || 配置文件格式 | v{格式版本} || 工作流模板 | v{模板版本} |
## 安全公告
| CVE/风险 | 严重级别 | 影响版本 | 修复版本 | 说明 ||----------|----------|----------|----------|------|| 安全公告编号 | 高/中/低 | ≤ {版本} | {版本} | 说明 |
## 已知问题
| 问题 | 影响 | 临时方案 | 预计修复 ||------|------|----------|----------|| 问题描述 | 影响范围 | 临时解决方案 | 目标版本 |
## 相关文档
- [CLI 快速入门](../批次1/cli-quickstart.md)- [CLI 故障排查](../批次1/cli-troubleshooting.md)- [CLI 工作流编排](../批次1/cli-workflow-orchestration.md)
---
> **文档版本**：v{版本号} | **最后更新**：{YYYY-MM-DD}3. 撰写规范
Section titled “3. 撰写规范”3.1 分类标准
Section titled “3.1 分类标准”每条变更必须归入以下分类之一：
| 分类 | 标识 | 内容范围 | 示例 |
|---|---|---|---|
| 新增功能 | Added |
全新功能、命令、参数、工作流节点 | 新增 railwise sync 命令 |
| 改进项 | Improved |
性能优化、体验提升、算法升级 | 数据导入速度提升 40% |
| 修复项 | Fixed |
Bug 修复、安全问题修复 | 修复 GSI-16 格式解析错误 |
| 破坏性变更 | Breaking |
不兼容的 API/配置/行为变更 | 移除 --legacy 参数 |
| 弃用项 | Deprecated |
即将移除的功能（提前通知） | railwise old-command 已弃用 |
| 移除项 | Removed |
已移除的功能、命令、参数 | 移除 v1.x 兼容模式 |
| 文档更新 | Docs |
仅文档变更，无代码变更 | 补充 API 文档示例 |
| 依赖更新 | Deps |
第三方依赖版本升级 | 升级 Bun 至 1.2.x |
3.2 撰写原则
Section titled “3.2 撰写原则”3.3 反模式示例
Section titled “3.3 反模式示例”| ❌ 错误写法 | ✅ 正确写法 | 问题说明 |
|---|---|---|
| “修复了一些 Bug” | “修复 GSI-16 格式文件导入时编码识别错误（#1234）” | 模糊、不可追溯 |
| “性能优化” | “水准测量平差计算速度提升 35%（10万测点从 12s 降至 7.8s）” | 无量化指标 |
| “新增功能” | “新增 railwise sync 命令，支持 TSM 实时数据双向同步” |
无场景说明 |
| “API 变更” | “--legacy 参数已移除，请使用 --format=v2 替代” |
无迁移指导 |
4. 发布流程
Section titled “4. 发布流程”4.1 发布前检查清单
Section titled “4.1 发布前检查清单”- [ ] 版本号符合 SemVer 规范- [ ] 所有变更已分类并写入日志- [ ] 破坏性变更已标注迁移方案- [ ] 安全漏洞已关联 CVE 编号（如适用）- [ ] 已知问题已列出临时方案- [ ] 相关文档已更新- [ ] 技术文档团队已审核- [ ] 产品经理已确认发布内容- [ ] 自动化测试全部通过- [ ] 回归测试完成（核心功能）4.2 发布流程图
Section titled “4.2 发布流程图”┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ 变更收集 │ → │ 日志撰写 │ → │ 内部审核 │ → │ 预发布验证 ││ (开发阶段) │ │ (技术文档) │ │ (产品+技术) │ │ (beta/rc) │└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ 正式发布 │ ← │ 发布公告 │ ← │ 文档上线 │ ← │ 全量测试 ││ (Git Tag) │ │ (社区/邮件) │ │ (知识库) │ │ (QA验证) │└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘4.3 发布渠道
Section titled “4.3 发布渠道”| 渠道 | 内容形式 | 目标受众 | 时效要求 |
|---|---|---|---|
| GitHub Releases | Markdown + 附件 | 开发者、开源用户 | 发布后 1 小时内 |
| 知识库 Changelog | 结构化文档 | 所有 CLI 用户 | 发布后 2 小时内 |
| 企业微信通知 | 摘要卡片 | 企业客户 | 发布后 4 小时内 |
| 邮件通知 | 详细变更列表 | 订阅用户 | 发布后 24 小时内 |
| npm registry | 包元数据 | 自动升级用户 | 同步发布 |
5. 版本支持策略
Section titled “5. 版本支持策略”| 版本系列 | 状态 | 支持截止 | 更新类型 |
|---|---|---|---|
| 最新 MAJOR | ✅ 活跃维护 | 下一 MAJOR 发布后 12 个月 | 功能 + 修复 + 安全 |
| 上一 MAJOR | ⚠️ 维护模式 | 当前 MAJOR 发布后 6 个月 | 仅修复 + 安全 |
| 更早版本 | ❌ 已停止 | 不再支持 | 无 |
- 建议所有用户保持升级到最新 PATCH 版本，以获取安全修复
- 生产环境使用 LTS（长期支持）版本，避免使用预发布版本
- 重大版本升级前，请在测试环境验证兼容性
6. 历史版本归档
Section titled “6. 历史版本归档”| 版本 | 发布日期 | 状态 | 归档链接 |
|---|---|---|---|
| v1.2.0 | 2026-06-15 | 活跃 | 查看详情 |
| v1.1.0 | 2026-04-20 | 维护 | 查看详情 |
| v1.0.0 | 2026-02-10 | 维护 | 查看详情 |
7. 相关文档
Section titled “7. 相关文档”- CLI 快速入门 — 安装与首次使用
- CLI 故障排查 — 常见问题与解决方案
- WorkWise 更新日志模板 — 桌面端产品更新规范
- OS 版本发布说明 — 业务系统版本发布规范
文档版本：v1.0.0 | 发布日期：2026-07-08 | 下次更新：2026-08-08