开源公共组件仓库的更新日志应该如何写
在 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://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.html ,以避免陈旧错误知识的误导,同时有更好的阅读体验。
如果你想持续阅读我的最新博客,请点击 RSS 订阅,推荐使用RSS Stalker订阅博客,或者前往 CSDN 关注我的主页
本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布,但务必保留文章署名林德熙(包含链接: https://blog.lindexi.com ),不得用于商业目的,基于本文修改后的作品务必以相同的许可发布。如有任何疑问,请 与我联系 。
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 【课后作业】ADS 层创建&数据接入
- 【项目实战】ADS 层复购率统计
- java设计模式-单例模式详解
- 技术迭代迷茫?Android资深架构师教你如何打破这个局面!
- 基于空间矢量的机器人动力学:铰接体惯量法matlab程序
- leetcode树之相同的树
- 1. 两数之和
- 突击并发编程JUC系列-原子更新字段类AtomicStampedReference
- 去除字符数组中指定的字符
- Android——Android Studio开发环境搭建及设置本地Gradle方法
- Java——类集框架:List集合接口的详解及应用举例
- Android——NORDIC nRF5x系列 DFU升级 APP实现
- Java——集合工具类(Collections工具类、Stack子类)
- Android——RecyclerView自定义OnScrollListener实现下拉刷新监听,上拉加载更多功能
- Java——类集框架:Map集合的详解及应用举例