在 GitHub 或 Gitlab 等开源的公共组件仓库里面，应该需要维护更新日志 CHANGELOG.md 文档，方便让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。但是没有任何一个能说服所有人的 更新日志 一定需要维护的原因，以及 更新日志 的文档格式

我推荐 keepachangelog 如何维护更新日志 的做法，以下是 https://keepachangelog.com 的中文内容

以下是一个例子，这是放在 OpenXML SDK 库的更新日志

## Version 2.12.0

### Added
- Added `OpenXmlCompositeElement.AddChild(OpenXmlElement)` to add children in the correct order per schema (#774)
- Added `SmartTagClean` and `SmartTagId` in place of `SmtClean` and `SmtId` (#747)
- Added `OpenXmlValidator.Validate(..., CancellationToken)` overrides to allow easier cancellation of long running validation on .NET 4.0+ (#773)
- Added overloads for `CellValue` to take `decimal`, `double`, and `int`, as well as convenience methods to parse them (#782)
- Added validation for `CellType` for numbers and date formats (#782)

### Removed
- Removed explicit reference to `System.IO.Packaging` on .NET 4.6 builds (#774)

## Version 2.11.3 - 2020-07-17
### Fixed
- Fixed massive performance bottleneck when IndexReferenceConstraint and ReferenceExistConstraint are involved (#763)
- Fixed CellValue to only include three most signficant digits on second fractions to correct issue loading dates (#741)
- Fixed a couple of validation indexing errors that might cause erroneous validation errors (#767)
- Updated internal validation system to not use recursion, allowing for better short-circuiting (#766)

## Version 2.11.2 - 2020-07-10

### Fixed
- Fixed broken source link (#749)
- Ensured compilation is deterministic (#749)
- Removed extra file in NuGet package (#749)

## Version 2.11.1 - 2020-07-10

更新日志是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒序的列表， 以记录一个项目中所有版本的显著变动。

为何要提供更新日志？

为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。

哪些人需要更新日志？

人人需要更新日志。无论是消费者还是开发者，软件的最终用户都关心软件所包含什么。 当软件有所变动时，大家希望知道改动是为何、以及如何进行的。

怎样制作高质量的更新日志？

指导原则

  • 记住日志是写给人的，而非机器。
  • 每个版本都应该有独立的入口。
  • 同类改动应该分组放置。
  • 版本与章节应该相互对应。
  • 新版本在前，旧版本在后。
  • 应包括每个版本的发布日期。
  • 注明是否遵守语义化版本格式.

变动类型

  • Added 新添加的功能。
  • Changed 对现有功能的变更。
  • Deprecated 已经不建议使用，准备很快移除的功能。
  • Removed 已经移除的功能。
  • Fixed 对bug的修复
  • Security 对安全的改进

如何减少维护更新日志的精力？

在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。

这样有两大意义：

  • 大家可以知道在未来版本中可能会有哪些变更
  • 在发布新版本时，可以直接将Unreleased区块中的内容移动至新发 布版本的描述区块就可以了

更多请看原文 keepachangelog 如何维护更新日志 的做法，以下是 https://keepachangelog.com

以下是补充原文的部分

添加更改链接

如 OpenXML SDK 库的更新日志就做的很好，包含了具体是那个 PR 更改了对应的内容，如下面内容

Fixed massive performance bottleneck when IndexReferenceConstraint and ReferenceExistConstraint are involved (#763)

此时的 #763 就是对应的 PR 链接，或 Issues 链接，这样方便小伙伴对更新日志好奇具体实现的时候，可以找到代码

本文会经常更新，请阅读原文： https://dotnet-campus.github.io//post/%E5%BC%80%E6%BA%90%E5%85%AC%E5%85%B1%E7%BB%84%E4%BB%B6%E4%BB%93%E5%BA%93%E7%9A%84%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97%E5%BA%94%E8%AF%A5%E5%A6%82%E4%BD%95%E5%86%99.html ，以避免陈旧错误知识的误导，同时有更好的阅读体验。

知识共享许可协议 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布，但务必保留文章署名 lindexi （包含链接： https://dotnet-campus.github.io/ ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。如有任何疑问，请 与我联系 。