管理日志对于保持你的 应用程序更新 透明和有条理。 本指南解释了如何为 Capacitor应用程序
- 创建、结构和自动化日志记录，确保开发者和用户都能得到通知。 以下是您将要学习的内容：为什么日志记录重要
- : 简化调试、改善沟通和建立用户信任。如何结构化日志记录
- : 使用类别“添加”、“修复”和“安全性”以提高清晰度。最佳实践 Capgo__CAPGO_KEEP_0__
- 自动化，并在拉取请求期间审查条目。: 使用 CI/CD pipeline 和提交标准来简化 changelog 管理。
- OTA 更新: 使用 __CAPGO_KEEP_0__ 等工具来自动创建 changelog,节省时间并确保一致性。使用 Over-the-Air (OTA) 解决方案,95% 的用户在 24 小时内更新。
快速提示: Automate changelog creation using tools like Capgo to save time and ensure consistency. 95% of users update within 24 hours using Over-the-Air (OTA) solutions.
快速提示
如何自动化项目的版本号和 changelog …
设置您的第一个 changelog
在您的 Capacitor 应用中跟踪和分享更新至关重要。以下是如何有效地结构它并遵循最佳实践。
changelog 格式选项
跟随 更新日志 标准化更新，按版本和类型组织。这种方法使用明确的分类，使更新变得容易理解：
| 分类 | 描述 | 示例条目 |
|---|---|---|
| 添加 | 新功能 | 添加推送通知支持 |
| 更改 | 现有功能的更新 | 更新了认证流程 |
| 弃用 | 即将移除的功能 | 即将废弃的遗留 API 接口 |
| 已移除 | 已移除的功能 | 已移除过时的分析 |
| 已修复 | 修复了 iOS 相机权限问题 | 安全 |
| 安全更新 | 增强数据加密 | 构建 CHANGELOG.md |
构建您的 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] 来简化更新 changelog 的过程。
- 审查过程: 将审查 changelog 条目作为您的 pull 请求过程的一部分。这样可以确保更新准确且在合并之前得到批准。
__CAPGO_KEEP_0__
在日志中写入清晰的更改日志条目
更改日志条目应该在技术精确性和可读性之间取得平衡，使其对开发者和用户都有用。
__CAPGO_KEEP_0__
- 遵循这些原则来确保您的更改日志条目清晰一致: 使用
- 现在时态 使用
- 动词 具体 说明发生了什么变化
- 提及依赖项版本更新
- 尽量避免使用专业术语
示例：
| 不明确的入口 | 清晰的入口 |
|---|---|
| 修复了bug | 修复iOS 17.4设备上的摄像头预览冻结问题 |
| 添加了内容 | 为Android添加生物识别身份验证支持 |
| 修改了API | 更新用户资料端点以支持新字段 |
| 安全修复 | 补丁 SQLite __CAPGO_KEEP_0__ |
Change Types and Categories
让用户快速找到他们关心的内容，组织更新分类。常见分类包括：
- Added: 引入新功能或功能
- Changed: 更新或修改现有功能
- Deprecated: 标记计划移除的功能或功能
- Removed: 表示已被移除的功能或功能
- 修复: 解决了 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. 提交参考
For major updates, reference the specific commit:
- Update authentication flow (commit: `8f4d89b`)Capgo 是开发者必备工具，能让他们更高效。避免 bugfix 的审查是黄金法则。” - Bessie Cooper
更新日志自动化工具
自动化更新日志创建简化了您的工作流程，并确保了项目的 Capacitor 变更记录的一致性。
最佳更新日志工具
几种工具可以有效地处理更新日志自动化。选择其中一个时，应重点关注以下关键特性:
- 版本检测:自动识别新版本
- 提交解析:从提交消息中提取相关细节
- 集成能力:完美地融入您的现有 CI/CD pipeline
- 自定义选项: 根据您的项目的具体需求进行定制
Capgo 通过实时更新来简化 changelog 自动化 [1]. 在超过 750 个应用程序中运行并交付 23.5 万次更新后，它已经证明了其可靠性。 [1]要充分利用这些工具，确保您的提交消息遵循清晰的结构。
提交消息标准
使用以下格式撰写提交消息：
[可选正文]
[可选尾部]
以下是常见的提交类型：
- feat: 用于引入新功能
- 修复: 用于解决bug
- 文档: 用于文档变更
- 样式: 用于格式化更新
- 重构: 用于重组 code 而不改变其行为
- 测试: 用于添加或更新测试
- 打杂: 用于一般性维护任务
CI/CD Changelog Setup
通过结合自动化工具和标准化的提交信息，您可以将更改日志生成集成到CI/CD管道中。这一设置确保了快速准确的更新。正确配置的管道可以自动生成更改日志、检查消息格式、更新文档并通知您的团队。
结果自说自话：95%的活跃用户在24小时内使用Capgo的自动部署系统接收更新 [1].
OTA更新日志管理
处理OTA更新的日志需要额外的关注，因为这些更新会立即部署。与用户下载手动的传统应用商店更新不同，OTA更新会自动到达设备。这使得清晰详细的文档对于维持用户信任并确保透明度至关重要。
OTA更新文档
管理实时更新时，重要的是要记录关键细节，如捆绑包版本、OTA更新版本、部署时间戳、成功率和用户采用度指标。为了使日志易于理解，组织更新到清晰的类别中：
| 类别 | 描述 | 示例条目 |
|---|---|---|
| 紧急修复 | 紧急修复立即问题 | ”Fixed crash in user authentication flow” |
| Feature Updates | New or improved functionality | ”Added dark mode support for dashboard” |
| Performance | Speed and optimization improvements | ”Reduced app loading time by 40%“ |
| Security | Updates to enhance safety | ”Enhanced data encryption for file transfers” |
Capgo Update Management
为了实现实时 OTA 更新，详细的文档是补充您的整体 changelog 策略的必需品。Capgo 简化了此过程，自动跟踪版本、监控更新性能、记录回滚和按渠道记录部署。
一名管理超过 5,000 名用户的开发人员分享了他们的经历：
“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]
实时 OTA 更新在生产环境中部署给我们的用户群体（+5000）后，我们看到的操作非常Smooth几乎所有用户在 OTA 部署到 @__CAPGO_KEEP_1__ 后几分钟内就已经更新了。:
- 实时 OTA changelog 管理最佳实践
- 尽快记录更改。
- 按渠道跟踪更新以支持分阶段部署。
快速解决问题时，记录回滚的清晰记录。
“We practice agile development and @Capgo is mission-critical in delivering continuously to our users!” – Rodrigo Mantica [1]
Summary
实时 OTA 是我们实时向用户交付的mission-critical工具！
有效的更改日志管理提高了清晰度并增强了用户信任。以下是几个关键实践：
| 实践 | 描述 | 影响 |
|---|---|---|
| 版本跟踪 | 跟踪应用程序和OTA的版本号。 | 82%的全球成功率 [1] |
| 更新类别 | 按类型（修复、功能、安全）分类更新。 95%的活跃用户在24小时内更新 | 部署记录 [1] |
| 有效的更改日志管理提高了清晰度并增强了用户信任。以下是几个关键实践： | 记录时间戳、成功率和指标。 | 支持监控 2350 万次更新 [1] |
| 回滚策略 | 与 OTA 集成的 OTA 日志管理 | 允许在必要时立即恢复 |
改善管理的建议工具
为了有效地实施这些实践，使用正确的工具至关重要。现代应用程序的现代化 Capacitor 将从工具 Capgo 中受益，后者简化了 changelog 管理，具有以下功能：
- 自动化版本控制: 使用 CI/CD pipeline 平滑地跟踪和记录更新
- 实时分析: 实时跟踪更新性能和用户采用率
- 频道管理: 在测试和滚动发布中启用beta测试和分阶段发布，实现更平滑的部署。
在选择日志管理工具时，优先考虑：
- 无缝集成: 与您的现有工作流程保持兼容。
- 详细文档: 自动跟踪部署数据。
- 用户更新: 对用户进行清晰、直接的沟通，说明变化。
通过结合这些实践和合适的工具，您可以建立一个可靠的日志系统，支持持续交付，同时保持用户知情。
“We practice agile development and @Capgo is mission-critical in delivering continuously to our users!” [1]
