管理changelog对于保持应用程序更新的透明和组织至关重要。这份指南解释了如何创建、结构和自动化changelog以便于开发者和用户了解。以下是您将要学习的内容： 为什么changelog重要？ ：它们简化了调试、改善了沟通和建立用户信任。 Capacitor apps：使用类别，如“添加”，“修复”，和“安全”以提高清晰度。
- 最佳实践__CAPGO_KEEP_0__ apps
- __CAPGO_KEEP_0__ apps__CAPGO_KEEP_0__ apps
- __CAPGO_KEEP_0__ apps: 在提交前更新更改日志，使用工具如 Capgo,并在 pull 请求期间审阅条目。
- 自动化工具: 使用 CI/CD pipeline 和提交标准来简化更改日志管理。
- OTA 更新: 使用版本号、时间戳和成功率等详细信息来记录实时更新。
快速提示: 使用工具如 Capgo 来自动化更改日志创建，节省时间并确保一致性。使用 Over-the-Air (OTA) 解决方案，95% 的用户在 24 小时内更新。
深入指南中设置您的第一个更改日志并将其无缝地集成到您的工作流中。
如何自动化项目的版本和更改日志以 …
设置您的第一个更改日志
Creating a clear changelog is key to tracking and sharing updates in your Capacitor app. Here’s how to structure it effectively and follow best practices.
更改日志格式选项
遵循 遵循 Keep a Changelog 标准以版本和类型为组织更新。这一方法使用清晰的类别使更新变得容易理解：
| 类别 | 描述 | 示例条目 |
|---|---|---|
| 添加 | 新功能 | 添加推送通知支持 |
| 已更改 | 现有功能的更新 | 更新的身份验证流程 |
| 已弃用 | 即将被移除的功能 | 废弃的遗留 API 接口 |
| 已移除 | 已被移除的功能 | 已移除过时的分析 |
| 已修复 | 修复的 bug | 修复了 iOS 相机权限 |
| 安全 | 安全更新 | 增强数据加密 |
构建您的 CHANGELOG.md
要设置您的 CHANGELOG.md确保它始终保持一致且易于阅读。将其放在您的项目根目录中，并包含以下主要元素：
- 标题部分: 添加您的项目名称和简短描述。
- 版本块: 在语义版本号 (MAJOR.MINOR.PATCH) 下记录更新。
- 发布日期: 使用 ISO 格式 (YYYY-MM-DD)。
2025-03-27. - 更改类别: 将更新归类到适当的标题下。
始终以倒序列出版本，以便最新的更新始终位于顶部。
在开发中添加 Changelog 步骤
将 changelog 更新整合到您的工作流程中确保准确和最新的文档。以下是一些实用的建议:
- 预提交更新: 在提交 code 变更之前更新 changelog。这有助于减少遗漏重要更新的机会。
- 自动化集成: 与 Capgo 类似的工具 GitHub Actions, GitLab CI, 和 Jenkins [1] 简化更新更改日志的过程.
- Review Process将查看更改日志条目纳入您的拉取请求流程中。这确保更新准确且已批准前合并.
Writing Clear Changelog Entries
更改日志条目应在技术精确性和可读性之间取得平衡，使其对开发人员和用户都有用.
Writing Style Guide
遵循这些原则以确保您的更改日志条目清晰一致:
- 以 现在时态
- 从 动词开始
- 具体说明变化 说明依赖项版本更新 尽量避免使用专业术语
- 示例：
- 不明确的入口
清晰的入口
| 修复bug | 修复iOS 17.4设备上的摄像头预览冻结问题 |
|---|---|
| 添加功能 | 为Android添加生物识别认证支持 |
| __CAPGO_KEEP_0__ | __CAPGO_KEEP_0__ |
| 修改了 API | 更新用户资料端点以支持新字段 |
| 安全修复 | 补丁 SQLite 在搜索函数中发现的注入漏洞 |
更改类型和类别
将您的更新组织成清晰的类别，以便用户可以快速找到他们关心的内容。以下是常见类别的分解：
- 添加：介绍新功能或功能
- ：更新或修改现有功能：删除或移除功能
- 已弃用: 标记计划移除的功能或特性
- 已移除: 表示已被移除的功能或特性
- 已修复: 解决了 bug 或问题
- 安全: 涉及到安全漏洞修复或更新
在分配类别时考虑用户的影响。例如，如果核心 API 更新了，列表它在“已更改”下，并提供必要的迁移细节。对于重大更新，链接到源代码以获取更多上下文。
添加参考链接
通过链接到相关文档、问题或提交来使您的更改日志更有帮助：
1. 问题参考
直接链接到与更改相关的GitHub问题或拉取请求:
- Fix iOS camera permissions dialog ([#234](https://github.com/your-repo/issues/234))2. 文档链接
当引入新功能或破坏性更改时，包括更新的文档链接:
- Add push notification support (See [Migration Guide](https://docs.example.com/push))3. 提交引用
对于重大更新，引用特定的提交:
- Update authentication flow (commit: `8f4d89b`)“Capgo is a must have tools for developers, who want to be more productive. Avoiding review for bugfix is golden.” - Bessie Cooper
Changelog Automation Tools
Automating changelog creation simplifies your workflow and ensures consistent documentation of changes throughout your Capacitor project.
Top Changelog Tools
Several tools can handle changelog automation effectively. When choosing one, focus on these key features:
- Version detection: Automatically spots new releases
- 提交解析: 从提交消息中提取相关细节
- 集成能力: 与您的现有 CI/CD pipeline 完美融合
- 自定义选项: 根据您的项目的具体需求进行定制
Capgo 通过实时更新简化了 changelog 自动化过程 [1]. 目前已有超过 750 个应用程序在生产环境中运行，23.5 万次更新已被交付 [1]它已经证明了其可靠性。 为了充分利用这些工具，确保您的提交消息遵循清晰的结构。
提交消息标准
为提交消息使用以下格式:
[可选正文]
[optional footer]
常见的提交类型包括:
- feat: 为添加新功能
- fix: 为修复bug
- docs: 为文档变更
- style: 为格式化更新
- refactor: 为重构code而无改变其行为
- 简体中文: 为添加或更新测试
- chore: 为一般维护任务
CI/CD Changelog Setup
通过结合自动化工具与标准化的提交信息，您可以将 changelog 生成集成到 CI/CD pipeline 中。这一设置确保快速准确的更新。一个正确配置的 pipeline 可以自动生成 changelog、检查消息格式、更新文档以及通知您的团队。
结果自说自话：使用 Capgo 的自动部署系统，95% 的活跃用户在 24 小时内接收更新 [1].
OTA Update Changelog Management
处理 OTA 更新的 changelog 需要额外的关注，因为这些更新会立即部署。与用户下载手动的传统应用商店更新不同，OTA 更新会自动到达设备。这使得清晰详细的文档对于维持用户信任并确保透明度至关重要。
OTA Update Documentation
在管理实时更新时，重要的是要记录关键细节，如捆绑包版本、OTA 更新版本、部署时间戳、成功率和用户采用度指标。为了使 changelog 易于理解，组织更新到清晰的类别：
| 类别 | 描述 | 示例条目 |
|---|---|---|
| 关键修复 | 紧急修复，立即解决问题 | ”用户身份验证流程中修复崩溃” |
| 功能更新 | 新功能或改进 | ”仪表板支持暗色模式” |
| 性能 | 速度和优化改进 | ”应用程序加载时间减少了 40%” |
| 安全 | Updates to enhance safety | ”Enhanced data encryption for file transfers” |
Capgo Update Management
For live OTA updates, detailed documentation is a must to complement your overall changelog strategy. Capgo simplifies this process by automatically tracking versions, monitoring update performance, logging rollbacks, and recording deployments by channel.
A developer managing over 5,000 users shared their experience:
“We rolled out Capgo OTA updates in production for our user base of +5000. We’re seeing very smooth operation almost all our users are up to date within minutes of the OTA being deployed to @Capgo.” – colenso [1]
Best Practices for OTA Changelog Management:
- 记录更新时的所有变更
- 通过渠道跟踪更新以支持分阶段发布
- 记录回滚以便快速解决问题
罗德里戈·曼蒂卡强调了这种方法的重要性：
“我们实践敏捷开发，@Capgo 在持续为用户交付方面是 mission-critical 的！” – 罗德里戈·曼蒂卡 [1]
概要
更改日志管理的关键实践
有效地管理更改日志可以增强清晰度并建立用户信任。以下是一些必不可少的实践：
| 实践 | 描述 | 影响 |
|---|---|---|
| 版本跟踪 | 跟踪应用程序和 OTA 的版本号。 | 82% 的全球成功率 [1] |
| 更新类别 | 按类型（修复、功能、安全）分类更新。 95%的活跃用户在24小时内更新。 | 部署记录 [1] |
| 记录时间戳、成功率和指标。 | 支持监控2,350万次更新 | 回滚策略 [1] |
| 维护以前版本的日志，支持OTA集成。 | 允许在必要时立即恢复。 | 建议的工具 |
为了有效地实施这些实践，使用正确的工具至关重要。现代__CAPGO_KEEP_0__应用程序从工具__CAPGO_KEEP_1__中受益，后者简化了更改日志管理，具有以下功能：
To implement these practices effectively, using the right tools is crucial. Modern Capacitor apps benefit from tools like Capgo, which simplifies changelog management with features such as:
- Automated Version Control: 使用 CI/CD pipeline无缝地跟踪和记录更新。
- 实时分析: 监控更新性能和用户采用率。
- 频道管理: 为更平滑的部署启用 beta 测试和分阶段发布。
选择 changelog 管理工具时，优先考虑：
- 无缝集成: 与您的现有工作流程兼容。
- 详细文档: 自动跟踪部署数据。
- 用户更新: 对变化进行清晰、直接的沟通。
通过结合这些实践和合适的工具，您可以建立一个可靠的日志系统，支持持续交付，同时保持用户知情。
“我们实行敏捷开发，@Capgo 在持续交付给用户方面是 mission-critical！” [1]
从 Capacitor 日志管理：终极指南继续前进
如果您正在使用 Capacitor 日志管理：终极指南 来规划回滚和版本控制，连接它与 回滚 查看回滚的实现细节在回滚中 版本目标 查看版本目标的实现细节在版本目标中 更新行为 查看更新行为的实现细节在更新行为中 bundle for the implementation detail in bundle, and Capgo实时更新 for the product workflow in Capgo Live Updates.
