管理更新日志对于保持您的 应用更新 透明且有序至关重要。本指南将介绍如何为 Capacitor 应用创建、构建和自动化更新日志，确保开发者和用户都能及时掌握动态。你将学习到：
- 为什么更新日志如此重要：它们能简化调试、改善沟通并建立用户信任。
- 如何构建变更日志结构：使用“新增”、“修复”和“安全”等分类以提高清晰度。
- 最佳实践：在提交前更新变更日志，并使用以下工具实现自动化： Capgo，并在 Pull Request 期间审查条目。
- 自动化工具：利用 CI/CD pipeline 和提交规范来简化变更日志管理。
- OTA 更新：记录 Live Update 的详细信息，如版本号、时间戳和成功率。
小贴士: 使用 Capgo 等工具实现 changelog 自动化生成，既能节省时间又能确保一致性。95% 的用户通过 Over-the-Air (OTA) 方案在 24 小时内完成更新。
深入阅读本指南，学习如何配置首个 changelog 并将其无缝集成到你的工作流中。
如何自动为项目进行版本管理和生成 changelog 以实现……
配置你的首个 Changelog
编写清晰的 changelog 是追踪并分享 Capacitor 应用更新的关键。以下是高效构建结构及遵循最佳实践的方法。
Changelog 格式选项
遵循 保持变更日志更新 标准，按版本和类型对更新进行分类。这种方法通过清晰的类别让更新内容一目了然：
| 类别 | 描述 | 示例条目 |
|---|---|---|
| 新增 | 新功能 | 新增推送通知支持 |
| 变更 | 现有功能更新 | 身份验证流程已更新 |
| 弃用 | 即将移除的功能 | 正在弃用旧版 API 端点 |
| 移除 | 已移除的功能 | 移除了过时的分析功能 |
| 修复 | Bug 修复 | 修复了 iOS 相机权限问题 |
| 安全性 | 安全更新 | 增强了数据加密 |
构建你的 CHANGELOG.md
为了配置你的 CHANGELOG.md，请确保其结构一致且易于阅读。将其放在项目的根目录下，并包含以下核心要素：
- 页眉部分：添加你的项目名称和简短描述。
- 版本区块: 按语义化版本号 (MAJOR.MINOR.PATCH) 记录更新。
- 发布日期: 使用 ISO 格式 (YYYY-MM-DD)，例如
2025-03-27. - 变更分类: 将更新内容归类到相应的标题下。
始终按时间倒序排列版本，确保最新的更新显示在最上方。
在开发流程中加入 Changelog 步骤
将 changelog 更新纳入工作流，可确保文档准确且保持最新。以下是一些实用技巧：
- 提交前更新: 在提交 code 变更前更新 changelog。这能减少遗漏重要更新的可能。
- 自动化集成：Capgo 等工具可配合 GitHub 操作, GitLab CI，以及 Jenkins [1] 使用，从而简化更新 changelog 的流程。
- 审核流程：将 changelog 条目审查纳入 pull request 流程。这能确保更新在合并前准确无误并已获得批准。
编写清晰的 Changelog 条目
Changelog 条目应在技术准确性与可读性之间取得平衡，使其对开发者和用户都具有参考价值。
编写风格指南
遵循以下原则，以确保您的 changelog 条目清晰且一致：
- 使用 一般现在时
- 以 动词开头
- 保持 具体 描述变更内容
- 提及依赖版本更新
- 尽量减少技术术语
示例：
| 模糊的记录 | 清晰的记录 |
|---|---|
| 修复 Bug | 修复 iOS 17.4 设备上相机预览冻结的问题 |
| 新增功能 | 新增 Android 生物识别身份验证支持 |
| 修改了 API | 更新用户资料接口以支持新字段 |
| 安全修复 | 补丁 SQLite 修复搜索功能的注入漏洞 |
更改类型与分类
将您的更新整理到清晰的分类中，以便用户快速找到所需内容。以下是常见的分类说明：
- 新增：引入了新特性或功能
- 变更：对现有特性进行了更新或修改
- 弃用：标记计划移除的特性或功能
- 移除：表示已删除的特性或功能
- 修复：解决了 Bug 或问题
- 安全性：包含与安全漏洞相关的补丁或更新
分配分类时请考虑对用户的影响。例如，如果核心 API 发生了更新，请将其列在“Changed”下，并在必要时提供迁移详情。对于重大更新，请附上源码链接以供参考。
添加参考链接
通过将条目链接到相关的文档、Issue 或 Commit，让你的 Changelog 更有参考价值：
1. Issue 引用
直接链接到与该变更相关的 GitHub Issue 或 Pull Request：
- Fix iOS camera permissions dialog ([#234](https://github.com/your-repo/issues/234))2. 文档链接
在引入新功能或破坏性变更（breaking changes）时，请附上更新后的文档链接：
- Add push notification support (See [Migration Guide](https://docs.example.com/push))3. Commit 引用
对于重大更新，请引用具体的 Commit：
- Update authentication flow (commit: `8f4d89b`)“Capgo 是追求高效开发者的必备工具。避免为修复 Bug 而进行重复评审是至关重要的。” —— Bessie Cooper
Changelog 自动化工具
自动化生成 Changelog 可以简化你的工作流，并确保你的 Capacitor 项目在变更记录方面保持一致性。
顶级 Changelog 工具
有多种工具可以高效实现 changelog 自动化。在选择时，请重点关注以下核心功能：
- 版本检测: 自动识别新版本发布
- Commit 解析: 从 commit message 中提取相关细节
- 集成能力: 无缝接入现有的 CI/CD pipeline
- 自定义选项: 根据项目的特定需求进行定制
Capgo 通过集成 Live Update 让 changelog 自动化变得更简单 [1]。目前已有超过 750 款应用投入生产，并完成了 2350 万次更新推送 [1]，它已证明了其可靠性。为了充分利用这些工具，请确保您的 commit message 遵循清晰的结构。
Commit Message 标准
请使用以下格式编写 commit message：
[可选的正文]
[可选的页脚]
以下是一些常见的 commit 类型：
- feat: 用于引入新功能
- fix: 用于修复 Bug
- docs: 用于文档变更
- style: 用于格式化更新
- refactor: 用于在不改变行为的情况下重构 code
- test: 用于添加或更新测试
- chore: 用于常规维护任务
CI/CD Changelog 设置
通过将自动化工具与标准化的 commit message 相结合，你可以将 changelog 生成集成到 CI/CD pipeline 中。这种配置可以确保更新快速且准确。配置良好的 pipeline 可以自动生成 changelog、检查消息格式、更新文档并通知你的团队。
结果显而易见：通过使用 Capgo 的自动化部署系统，95% 的活跃用户能在 24 小时内收到更新 [1].
OTA Update Changelog 管理
由于 OTA 更新是即时部署的，因此处理其变更日志（changelog）需要格外谨慎。与用户手动下载的传统应用商店更新不同，OTA 更新会自动推送到设备。因此，清晰且详尽的文档对于维护用户信任和确保透明度至关重要。
OTA 更新文档
在管理 Live Update 时，记录关键细节非常重要，例如 bundle 版本、OTA 更新版本、部署时间戳、成功率以及用户采用率指标。为了让变更日志易于理解，请将更新分为以下清晰的类别：
| 类别 | 描述 | 示例条目 |
|---|---|---|
| 关键修复 | 针对紧急问题的即时补丁 | “修复了用户身份验证流程中的崩溃问题” |
| 功能更新 | 新增或改进的功能 | “为 dashboard 添加了暗黑模式支持” |
| 性能 | 速度与性能优化 | “应用加载时间缩短了 40%” |
| 安全性 | 安全性增强更新 | “提升了文件传输的数据加密强度” |
Capgo 更新管理
对于 Live Update OTA 更新，详细的文档是完善整体变更日志策略的必备环节。Capgo 通过自动追踪版本、监控更新性能、记录回滚日志以及按渠道记录部署情况，简化了这一流程。
一位管理着 5,000 多名用户的开发者分享了他的经验：
“我们向 5,000 多名用户推送了 Capgo OTA 更新。运行非常平稳，几乎所有用户在 OTA 部署到 @Capgo 后几分钟内就完成了更新。” – colenso [1]
OTA 更新日志管理最佳实践:
- 变更完成后立即记录。
- 按渠道追踪更新，以支持分阶段发布。
- 保留清晰的回滚记录，以便快速解决问题。
Rodrigo Mantica 强调了这种方法的重要性：
“我们采用敏捷开发，@Capgo 对于向用户持续交付至关重要！” – Rodrigo Mantica [1]
总结
更新日志管理的关键实践
高效管理更新日志可以提高透明度并建立用户信任。以下是一些核心实践：
| 实践 | 描述 | 影响 |
|---|---|---|
| 版本追踪 | 跟踪版本号（App 和 OTA）。 | 被追踪更新的全球成功率为 82% [1] |
| 更新分类 | 按类型对更新进行分类 （修复、新功能、安全更新）。 | 95% 的活跃用户会在 24 小时内完成更新 [1] |
| 部署记录 | 记录时间戳、成功率及各项指标。 | 支持监控 2350 万次更新 [1] |
| 回滚策略 | 通过 OTA 集成保留历史版本日志。 | 必要时可立即恢复。 |
提升管理效率的推荐工具
要有效实施这些实践，选对工具至关重要。现代 Capacitor 应用可以借助 Capgo 这类工具，通过以下功能简化 changelog 管理：
- 自动化版本控制: 利用 CI/CD pipeline 无缝追踪并记录更新。
- 实时数据分析: 持续关注更新表现和用户采用率。
- Channel 管理: 支持 Beta 测试和分阶段发布，让部署更顺畅。
在选择 changelog 管理工具时，请优先考虑：
- 无缝集成: 与现有工作流的兼容性。
- 详细文档：自动追踪部署数据。
- 用户更新：清晰、直接地告知变更内容。
通过将这些实践与合适的工具相结合，您可以建立一个可靠的 changelog 系统，在支持持续交付的同时，让用户随时掌握最新动态。
“我们采用敏捷开发，@Capgo 对于持续向用户交付至关重要！” [1]
继续阅读 Capacitor Changelog Management: Ultimate Guide
如果你正在使用 Capacitor Changelog 管理：终极指南 以规划回滚和版本控制，并将其与以下内容连接： 回滚 查看 Rollbacks 中的实现细节， 版本定向 关于版本目标选择 (Version Targeting) 的实现细节， 更新行为 关于更新行为 (Update Behavior) 的实现细节， bundle 关于 bundle 的实现细节，以及 Capgo Live Updates 用于 Capgo Live Updates 中的产品工作流。
