定义
Changelog（变更日志）记录 OTA 固件版本的更新内容、修复项与已知问题，便于运维与客户了解版本差异，辅助升级决策。常与 CI/CD 流水线集成自动生成。
内容规范
Changelog 通常按版本号组织，每条记录包含：新增功能（Added）、修复问题（Fixed）、已知问题（Known Issues）、破坏性变更（Breaking Changes）等分类。采用语义化版本（SemVer）时，可对应 Major.Minor.Patch 的变更级别。格式可遵循 Keep a Changelog 等规范，便于机器解析与人工阅读。
自动化生成
在 CI/CD 流水线中，可从 Git 提交信息、Issue 关联、PR 描述自动生成 Changelog 条目。工具如 conventional-changelog 可根据 Conventional Commits 规范解析提交，减少人工维护成本，确保每次 OTA 发布都有可追溯的变更说明。
与 OTA 发布流程结合
设备管理平台在创建 OTA 任务时，可关联 Changelog 内容，在升级确认界面展示给运维人员或客户。对于灰度升级、分批推送场景，清晰的 Changelog 有助于评估升级风险，决定是否扩大推送范围或执行 Rollback 回滚。
一条版本说明至少要写清什么
变更日志的技术含义，是给每一个可下发的固件版本一份人和机器都能对照的差异说明，而不是仓库提交记录的原文粘贴。它要回答：相对哪一个旧版本、改了什么行为、修了什么缺陷、还有什么没修、哪些改动会导致旧配置或旧协议不再适用。版本号、发布时间和适用产品要写在同一条里。只写“优化稳定性”无法判断某台卡在旧版本上的设备该不该升。日志应随版本冻结，已发布条目不随口头解释改写；若发现写错，应追加更正，而不是悄悄替换历史。
适合强制附带变更日志的场合，是版本会通过空中升级到达现场，并且现场存在多个旧版本。实验室内部的临时包如果不会离开测试分组，可以用简短记录，但一旦进入可选择的发布列表，就应补全。说明要能对应到增量包所声明的源版本：从甲版本到丙版本的差异，不能拿乙版本的说明去凑。破坏性改动要单独列出，例如属性改名、默认阈值变化、启动分区布局调整，因为这些决定了能否直接覆盖安装。
说明过粗导致误升级
常见错误是把几天的提交标题合并成一句“修复若干问题”，运维无法判断本次是否包含自己等待的那一个缺陷。另一种是只写新增功能，不写已知问题和回退限制，灰度阶段出现异常时，看日志仍像一次普通发布。版本号跳号却不说明中间版本是否必须经过，也会让增量升级路径和说明对不上。从提交信息自动生成时，如果开发用含糊的提交标题，生成结果同样含糊，自动化并不能代替审阅。
还要避免把尚未合并的改动提前写进已发布版本，或把试验功能写成默认开启。设备端行为若依赖编译开关，日志里应写明这一版实际打开了哪些开关。与固件签名的关系是：签名保证包没有被掉包，变更日志保证人理解包里有什么，两者不能互相代替。发布后才补的“其实还有一个协议变更”，应视为说明事故，需要重新评估已经升级的设备，而不是只改网页上的文字。
已发布说明发现写错时
版本已经能够被设备下载之后，变更说明就和那个包绑在一起。发现漏写了协议变更或把缺陷号写错，正确的做法是在原条目下追加更正，注明更正时间和更正了哪一句，而不是把原文替换得像从未错过。替换会让已经根据旧说明做出升级决定的人无法解释自己为什么放行。若错误严重到会影响已升级设备的安全或兼容，应另外发布说明，指出哪些版本受影响、建议停在哪一版或继续升到哪一版，而不是只改网页标题。尚未发布、还在候选区的说明则可以改，但要保证最终发布的文字和最终包是同一候选。
自动从提交标题生成的草稿，发布前要由了解行为变化的人读过。提交标题里的内部代号、取消的实验和并未合入的修复，都不该出现在给升级决策看的正文里。相反，默认阈值、分区布局、配置字段名称这些用户能感知的变化，即使提交标题没写，也要补进说明。一份说明如果不能回答“从我现在的版本升上去，旧配置还能否使用”，它就还不够格随包发布。已知问题写“无”之前，应确认这一版确实没有未关闭且影响升级的缺陷，而不是因为没人填写就空着。若更正涉及已在现场运行的版本，还应指出受影响的版本范围和建议的下一步，而不是只在页面底部追加一句不起眼的备注。