Vico Bill< 刘 利 波 > 的个人网站

记录关于学习、工作中的技术点滴

C,C++,Rust,Ruby爱好者;热衷于游戏开发、任务自动化与跨平台;沉迷于游戏引擎与图形表现;深信'简单、多元'哲学的力量。


访问主页

笔记集锦——ChangeLog规范

前言

作为一个普通的开发者,我必须为我的项目维护一个更新日志(以下简称 changelog)吗?

  • 如果你在维护一个开源项目,或者公司内部的底层技术产品,那么提供一个 changelog 是必需的。开发者用户很可能需要从一个低版本升级到最新版,changelog 可以帮助他们了解新版本有哪些变化。
  • 如果你在开发一个业务应用,那么 changelog 不是必需的。然而提供一个 changelog 会更好,因为其他协作者或是交接方能更直观地看到业务逻辑的演变。

我记得你还约束了 Git log 的规范,那为何还要再规范 changelog 的格式呢?两者不是差不多?

  • 即便是约束了 Git log 的规范,也无法直接将 Git log 导出一个良好的 changelog。因为 changelog 中描述的内容需要更加精炼和归纳,对信息降噪处理等等,因此手写 changelog 仍然是更好的选择;当然,不排除以后自动转换的可能。
  • 不管是手写还是自动转换,changelog 的格式都不能直接照搬 Git log 的格式。这两者的区别与联系同在。

changelog 文件

changelog 文件必须取名为 CHANGELOG.md,存放在项目的根目录下,和 README.mdCONTRIBUTING.md 等并列,同时保持风格一致。

这种命名方式已然是国际通则,以下再阐释一番:

使用大写来表明本文件的重要性,相当于是项目仓库元信息的一部分。 使用 .md 作为后缀,而不是 .txt 或干脆不加后缀。使用标准 Markdown 语法,从而可以方便地渲染。

基本的 changelog 格式

# 更新日志

## [<version>] - <date>

### <type>

* <desc>
* <desc>

### <type>

* <desc>
* <desc>

[<version>]: <version-diff-url>

其中,按照最新的版本号在前的顺序排列。

词汇表

标题

标题部分使用固定的文案:「更新日志」。

如果是面向国际的项目,需要使用英文,则文案为「Change Log」。

version

版本号 version 即项目的每一个发布版所使用的版本号。版本号需遵循 SemVer 版本号命名规范。

注意:版本号前不要加 v

另外,版本号建议增加一个链接,指向当前版本和上一个版本之间的 diff。详情可参考后文的样本示例。

date

发布时间 date 即版本发布时的所在日期。

日期采用 yyyy-MM-dd 的格式。

示例:

// good
2016-01-01

// bad
2016-1-1
20160101

type

更新类型 type 用以说明更新的方面。这里的 type 和 Git 提交日志中的 type 有所联系,然而并不一一对应。

同前面提到的「标题」部分,默认使用中文版本的词汇,如果是面向国际的项目,则使用括号中的英文版本。

type 的可选值如下:

  • 新增(Features):新增功能。可简写为+

  • 修复(Fixed):修复 bug。

  • 变更(Changed):对于某些已存在功能所发生的逻辑变化。

  • 优化(Refactored):性能或结构上的优化,并未带来功能的逻辑变化。

  • 即将删除(Deprecated):不建议使用 / 在以后的版本中即将删除的功能。

  • 删除(Removed):已删除的功能。

    desc

描述内容 desc 需要注意:

  1. 使用完整的句子。即在标点方面遵循一般的文档格式规范;如果使用英语,则句首大写。
  2. 时态方面使用一般现在时,不要用过去时态。虽然查看 changelog 时,changelog 内容本身都发生在过去,然而使用现在时的时态更简洁明确,并且更易达成一致性。
  3. 句式使用祈使句式。即一般情况不要增加主语。因为在绝大情况下,主语都是作者「我」。
  4. 注明修复的问题。如有提过 issue,则在句尾增加 issue 的 ID 和链接。

[^ KeepChangeLog](https://keepachangelog.com/zh-CN/1.0.0/)

最近的文章

笔记集锦-Nginx

Nginx 是优秀的HTTP Proxy, Mail Proxy以及流式TCP/UDP服务器.使用Nginx配置虚拟主机nginx.conf中会有include字段,可包含不同的配置文件.主机配置文件主要在:# 加载启用的模块的配置include /etc/nginx/modules-enabled/*.conf;# http代理配置http { # 包含其他相关http代理配置 include /etc/nginx/conf.d/*.conf; ## 主要是网站配置 ...…

继续阅读
更早的文章

笔记集锦-Elixir

核心:匹配=号是匹配.表示左边和右边互相匹配值.<- 匹配,但匹配失败时,不会报错,而是返回nil值.不可变所有值,一旦创建就不可再改变.基础 整数: 任意大小的整数 浮点数 原子: 全局唯一名称 区间Range: start..end 正则表达式: 可用~r/../ 或其他~r{..} 等sigil包裹. 在Regex模块中. PID和端口: 进程ID.端口表示可读写的资源引用.self表示自身进程. 引用.全局唯一引用.复合数据类型: 元组...…

继续阅读