Skip to content

开源公共组件仓库的更新日志应该如何写

Updated: at 08:22,Created: at 06:25

在 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)是一个由人工编辑,以时间为倒序的列表, 以记录一个项目中所有版本的显著变动。

为何要提供更新日志?

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

哪些人需要更新日志?

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

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

指导原则

变动类型

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

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

这样有两大意义:

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

以下是补充原文的部分

添加更改链接

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

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

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


知识共享许可协议

原文链接: http://blog.lindexi.com/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

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