ShinKouyo の 小栈

关于 Arch Linux 软件包打包的提交信息

创建于 , 最后更新于

根据 CC0 1.0 Universal 之条款, 将本作品贡献至公有领域, 放弃其全部著作权及相关权利和邻接权利, 不提供任何担保

根据 Arch Linux 官方软件包仓库的 Git 存储库, 让 LLM 总结了其提交规范.

1. 概述

提交信息中的所有文本必须使用英文编写.

提交信息的格式如下:

[可选 前缀]: <描述>

[可选 正文]

[可选 脚注]

各字段含义:

  • 前缀 (prefix): 一个名词, 说明提交的性质或变更影响的模块. 版本更新提交必须使用 upgpkg; 其他提交可以使用模块名作前缀 (如 config, nvchecker), 也可以省略. 可选.
  • 描述 (description): 变更的简短总结. 紧跟冒号和空格, 必须存在.
  • 正文 (body): 提供额外上下文的详细说明. 可选.
  • 脚注 (footer): 包含结构化元数据 (如引用, 署名). 可选.

2. 术语

本文中的关键词 “必须 (MUST)”, “禁止 (MUST NOT)”, “必要 (REQUIRED)”, “应当 (SHALL)”, “不应当 (SHALL NOT)”, “应该 (SHOULD)”, “不应该 (SHOULD NOT)”, “推荐 (RECOMMENDED)”, “可以 (MAY)” 和 “可选 (OPTIONAL)” 的解释参考 RFC 2119.

3. 规范

3.1. 版本更新提交 (upgpkg)

版本更新提交必须使用 upgpkg 前缀. 格式如下:

upgpkg: <pkgver>-<pkgrel>[: <原因>]

pkgver 和 pkgrel 必须与 PKGBUILD 中的实际值一致. pkgver 可以包含 epoch (如 2:2.14-1), git 快照 (如 2:2.12.r418.g6b5c671d-2) 或日期 (如 2024.04.07).

当 pkgrel 大于 1 (重建或重打包) 时, 必须写明原因. 原因紧跟冒号或分号, 推荐使用冒号; 多个原因可以使用分号串联.

推荐的原因写法:

  • new upstream release — 新上游版本发布
  • update to latest version — 更新到最新版本
  • <工具链> <版本> rebuild — 工具链或依赖重建, 如 gcc 16.2.1 rebuild, glibc 2.42 rebuild, Python 3.14 rebuild
  • [core] mass rebuild — 全树批量重建
  • <具体说明> — 特定修复或变更, 如 backport two fixes

版本更新提交不得以裸版本号作为完整消息 (如 7.1.8.arch1-1). 裸版本号消息仅允许由自动化工具生成.

3.2. 前缀 (prefix)

除 upgpkg 外, 提交可以使用模块名作为前缀, 指明变更影响的模块或组件. 模块名后必须紧跟冒号和空格.

常见模块前缀: config, nvchecker, hook, reuse, sd-encrypt, gitignore, tree-wide, PKGBUILD, mkinitcpio, sysctl.

3.3. 描述 (description)

描述是对变更的简短总结. 它必须直接跟在冒号和空格之后, 并且必须位于同一行内.

描述应该以动词开头, 首字母小写, 末尾不应该有句号. 推荐长度不超过 50 个字符, 不应该超过 72 个字符.

推荐使用的动词: add, remove, update, fix, drop, use, enable, disable, switch, move, bump, backport, cherry-pick, sync, revert, consolidate, simplify, set.

3.4. 正文 (body)

正文是可选的, 用于提供额外上下文. 推荐仅在以下场景使用:

  • 解释变更的动机或原因
  • 引用相关链接 (todo 页面, issue, 上游提交)
  • 以列表形式列出多项变更
  • 粘贴外部证据 (构建输出, 上游提交清单)

如果存在正文, 必须从描述后的空行开始. 正文可以自由格式, 允许使用空行分段和 - 列表.

脚注是可选的, 位于正文之后, 以一个空行分隔. 它可以包含一行或多行.

每行脚注必须包含一个令牌 (token), 后跟 : 作为分隔符, 再跟具体值. 令牌必须使用连字符 (如 Related-to), 且必须首字母大写.

推荐使用的脚注令牌:

  • Fixes: — 修复某个 issue, 值为完整 URL
  • Closes: — 关闭某个 issue 或 todo, 值为完整 URL
  • Related-to: — 引用相关的 issue, PR 或链接, 值为完整 URL
  • See: — 相关的其他资源或链接
  • Signed-off-by: — 标注签署人, 格式为 姓名 <邮箱>
  • Co-authored-by: — 标注共同作者

问题引用必须使用完整 URL.

修复安全漏洞的提交必须引用 CVE 或 AVG 编号.

3.6. merge 和 revert

合并提交必须使用 git 的默认模板, 不需要自定义:

Merge branch '<分支名>'

还原提交必须使用 git 的默认模板:

Revert "<被还原提交的主题>"

This reverts commit <被还原提交的哈希>.

3.7. 批量操作提交

由全树统一执行的批量操作 (政策变更, 许可规范化, 全树重建) 必须复用既有的标准消息, 不得自创措辞. 常见标准消息:

  • License package as 0BSD
  • Remove i686 from arch=()
  • [core] mass rebuild
  • Drop options=(debug) from trunk
  • add nvchecker.toml
  • add .SRCINFO

3.8. 语言和风格

提交信息中的所有文本必须使用英文编写.

提交信息不得包含口语化表达, 情绪化词语, emoji 或表情符号, 也不得包含拼写错误.

4. 示例

4.1. 版本更新 (新上游版本)

upgpkg: 2.14.1-1: new upstream release

4.2. 版本更新 (工具链重建)

upgpkg: 2.14.1-2: glibc 2.42 rebuild

4.3. 版本更新 (多个原因)

upgpkg: 4.19.0-2; rebuild to add .SRCINFO; SPDX license

4.4. 常规改动

add missing dependency to makedepends

4.5. 带模块前缀的改动

config: Set TRANSPARENT_HUGEPAGE_{TMPFS,SHMEM}_HUGE_ADVISE

4.6. 修复 (带脚注)

Fix typo in setup script

Fixes: https://gitlab.archlinux.org/archlinux/packaging/packages/foo/-/issues/123

4.7. 多行正文和脚注

Lock alpm system user

The alpm system user can be locked, preventing any form of login or
direct user usage.

Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>

4.8. 要点列表正文

Simplify the calls to configure and make

Use a sorted bash array for the configure options, as that is easy to
handle and read.

4.9. 批量操作提交

License package as 0BSD

This implements RFC40 and RFC52.
https://lists.archlinux.org/archives/list/arch-dev-public@lists.archlinux.org/thread/XR3VAUWC5LNMTVOCKFOHYYEGUQ4ZFCNG/

4.10. 合并提交

Merge branch 'release/2.14'

4.11. 还原提交

Revert "add missing dependency to makedepends"

This reverts commit 676104e2.