Logo

菜单

发布于 2026-01-06 1 阅读
0

博客文章：为什么以及如何编写好的变更日志

博客文章：为什么以及如何编写好的变更日志

在这篇博文中，我将概述我对变更日志的看法，以及变更日志应该如何编写和组织，以及编写和组织的原因。请注意，这基于我的经验和观点，并非一套最佳实践，而仅仅是我在软件（尤其是开源软件）工作中，通过阅读和编写变更日志而总结出的一些实践经验。

无论软件项目大小，编写变更日志都是个好习惯。变更日志通常以单个文本文件的形式存在，与脚本、库或应用程序一起保存，是软件开发或项目的核心。

通过文字进行沟通时，为了成功传达信息，需要牢记几个重要的关键点。

  • 本文的目标读者是谁？
  • 读者为什么要阅读这篇文章？

这些都是非常基础的问题，答案似乎也很简单明了，但是你在编写文本时，尤其是在编写变更日志时，是否记得问自己这两个重要的问题？

那么，我们来尝试设置编写变更日志的条件。我们可以使用故事格式来实现，将其描述为一个基本用例。

我的软件用户正在查看我的变更日志，以确认之前
报告的错误是否已得到解决。

我们之所以要如此具体，是为了理解变更日志的作用及其重要性。

变更日志扮演着特殊的角色，这使其与其他文档有所区别。主要文档描述了软件的理想用法，可能包含一些限制，也可能提及待办事项列表、教程或其他内容，但软件的主要用例在其他地方已有描述，并且通常会随着软件的更新而更新，这意味着它记录的不是变更本身，而是当前状态，例如从先前状态的迁移，或者传达现有功能和新功能的弃用或引入信息。变更日志的作用单一但至关重要，它负责传达软件的变更信息。

深入探讨文档的结构化和相关的沟通任务超出了这篇博文的范围，或许应该用同样的方式来探讨，我确实有一些关于文档的经验和看法，但我们还是回到正题吧。

主要文档适用于以下使用场景：

  • 弄清楚软件的功能，甚至可能包括它的工作原理。
  • 如何安装、配置、使用，甚至如何排除故障
  • 如何卸载
  • 或许可以了解如何获得支持或联系作者。

但一切都与当前软件版本密切相关，并且如前所述，可能还包含迁移和弃用信息。

让我们来看另一个使用案例。

我的软件用户发现了一个问题，问题指向我的软件。
他没有逐行检查数千行代码，而是
快速浏览了变更日志，看看是否有任何列出的更改可能是问题的原因。

这引出了另一个沟通的关键点，这在软件使用场景中可能非常重要，但在紧急情况下进行的其他文本交流中也可能非常重要。

  • 读者何时阅读文本？

有人正在努力工作，可能正在加班加点地解决软件问题或其他类似问题，他们压力很大，而且时间紧迫。他们遇到了与我们刚才描述的用例类似的问题，必须尽快弄清楚是否是您的软件更新导致了这个问题，然后决定是寻找其他解决方案、实施临时方案还是回滚。

这时变更日志就派上用场了。

变更日志是对变更的简短、简洁的描述，遵循一定的标准布局，以便于阅读。

现在让我们来看看如何构建变更日志，以便更好地适应这些用例。

添加标题

文件名含义模糊，因此请在文件顶部添加标题。

Change log for ApplicationX

条目应以标题加子项列表的形式组织。

条目应以对所描述的版本进行指示开始，本示例使用语义化版本控制（semver），我稍后会详细介绍，然后列出每个更改。

1.0.1
- Fixed bug in parser
Enter fullscreen mode Exit fullscreen mode

按时间倒序排列条目

通常情况下，使用场景是查找最近的更改，因此随着时间的推移，历史更改的重要性会越来越低，最终会移到文档的末尾。

1.0.1
- Fixed bug in parser

1.0.0
- Initial release
Enter fullscreen mode Exit fullscreen mode

构建发布条目

发布条目应采用统一的格式。

它至少应该包括：

  • 版本号
  • 时间戳

是否使用语义化版本控制取决于您。但必须采用可识别的版本控制方案，以便对每个版本进行唯一标识。

1.0.1 2018-09-27
- Fixed bug in parser

1.0.0 2018-09-27
- Initial release
Enter fullscreen mode Exit fullscreen mode

我见过带有时区且精确到小时、分钟和秒的时间戳，但这可能没有必要，因为发布的影响可能与实际部署等操作的影响不同，所以恕我直言，这些额外的信息有点过头了。

日期格式要保持一致，建议采用ISO-8601日期格式。

我发现一些额外的元数据非常有用，例如发布类型指示：

  • 功能发布
  • 维护版本
  • 错误修复版本

这些内容与语义版本控制方案没有直接对应关系，但它们提供了一些关于如何进行版本控制的信息。

1.0.2 2018-09-27 Maintenance release
- gitignore updated with tmp directory

1.0.1 2018-09-27 Bug fix release
- Fixed bug in parser

1.0.0 2018-09-02 Feature release
- Initial release
Enter fullscreen mode Exit fullscreen mode

用户可以查看版本说明，并判断该功能版本中包含的功能目前对他们是否有用，或者是否可以暂时跳过。

如果只是一个维护版本，用于解决元数据或发布信息中的一些小问题（相信我，这些年来我犯过不少这样的错误），那么现在或许可以跳过它。

最后，错误修复版本表明，没有添加任何新内容，向后兼容性保持不变，错误已得到解决，对于想要查看其问题是否已解决的用户来说，此信息价值连城。

有些错误修复可能意义重大，因此向用户暗示他们对该版本的立场可能很重要。

我用的是这两个：

  • 建议更新
  • 无需更新
1.0.2 2018-09-27 Maintenance release, Update not required
- gitignore updated with tmp directory

1.0.1 2018-09-27 Bug fix release, Update recommended
- Fixed bug in parser

1.0.0 2018-09-02 Feature release
- Initial release
Enter fullscreen mode Exit fullscreen mode

结构变更项目条目

现在我们的发布条目结构已经就绪，现在让我们来看看变更条目。

发布版本中的单个项目应以人类可理解的方式进行描述，每个变更集应使用单个条目进行描述。

我见过将条目分组为以下几种情况：

  • 新增功能
  • 错误修复

是的，这应该是整体变更条目结构的一部分，但由于我的目标是保持版本较小，并将其分为错误修复版本或功能版本，所以我尽量不将它们混合在一个版本中。

如果你发布包含多项更改的大型版本，例如主要版本，这种分离方式会非常有用，例如，如果你定期发布计划版本的话。

2.0.0 2018-09-27 Feature release, Update recommended

Feature additions:
- Added color selector
- Added color profile exporter

Bug fixes:
- Addressed issue with start up time
Enter fullscreen mode Exit fullscreen mode

为了避免在变更日志中重写所有内容，请添加链接和引用。

1.09 2018-05-30 Bug fix release, update not required

- Based on issue #21 several issues with the test suite was spotted
  and corrected, at the same time there was created issues for
  implementation of adapters for SK and NZ. An issue with ES was also
  created since this distribution seems to rely on Date::Holidays,
  which does not seem to make sense.

  Ref: https://github.com/jonasbn/Date-Holidays/issues/21
Enter fullscreen mode Exit fullscreen mode

请使用被动语态，不要使用主动语态。我见过太多次这种情况了，人们直接从待办事项列表或问题跟踪器等地方复制粘贴。提交日志中也经常出现这种情况——在我看来，这简直是粗心大意。

例子：

你的问题跟踪系统中有以下任务：

“添加颜色选择器”

这说明还有事情需要完成。

然后在变更日志中添加：

“新增颜色选择器”

这表明某件事已经完成。

以上是我对基本变更日志的建议，现在让我介绍一些相关信息。

自动生成变更日志

我见过一些尝试从提交日志或其他类似数据自动生成变更日志的方法。我不建议这样做。

变更日志扮演着重要的角色，它是一种沟通媒介，而不仅仅是变更列表。如果您要编写变更日志，我认为应该考虑以下标准。

这完全可以实现，以上两条标准对于正常的提交纪律来说都是合理的建议，但我从未见过/参与过一个足够成熟或纪律严明的项目来做到这一点——并不是说我不努力做到这一点，而是这很难。

其中一个潜在问题是，我认为变更日志的生成不应该决定你与谁合作或采用何种流程。但如果你遇到可以自动生成变更日志的情况，请告诉我，我很乐意了解。

额外提示：使用 Markdown 编写

内容有点多，文章也比预期的要长，但我必须把这些额外信息塞进去。

考虑使用Markdown编写变更日志。

  • 这样可以缩短链接，这些链接会被渲染成超文本而不是文本，是的，超链接就是很酷——感谢伯纳斯-李先生。
  • 如有需要，您可以使用粗体、斜体和代码块。

最后，您可以使用不同的标题来组织您的版本条目，次要版本可以包含在主要版本中。

## 2.0.0 2018-09-27 Feature release, Update recommended
- Added colour selector

### 1.0.1 2018-09-03 Bug fix release, Update recommended
- Fixed bug in parser

## 1.0.0 2018-09-02 Feature release
- Initial release
Enter fullscreen mode Exit fullscreen mode

感谢您阅读到最后，请在评论区留下您的想法/问题等。

文章来源：https://dev.to/jonasbn/why-and-how-should-you-write-a-good-change-log-4kp0
更新：Bootstrap v5.0...
2025 年学习 Kubernet...