获取 Gentoo!
开发者指南
  1. 主索引
  2. Ebuild 维护

Gentoo 开发者指南

本指南涵盖了 Gentoo ebuild 开发中 Git 使用说明和策略。它假设读者具备基本的 Git 知识。有关通用指南，请参阅官方的 Git 书籍。

准备开发检出

克隆 gentoo.git 仓库

Ebuild 开发发生在官方 Git 仓库上。您只能通过 SSH 协议推送更改。因此，请使用以下命令克隆仓库：

git clone [email protected]:repo/gentoo.git

如果您没有 SSH 访问 Gentoo Git 服务的权限，您可以使用 anongit 镜像进行只读访问。

git clone https://anongit.gentoo.org/git/repo/gentoo.git

通常，Git 会从 Git 仓库的起始时间（2015 年 8 月）获取完整历史记录。这可能需要大量的磁盘空间。如果您不需要完整历史记录，可以使用 --depth 选项创建浅克隆，仅包含包含最新提交的子集。例如，--depth=50 将包含最新的 50 个提交。

请注意，使用浅克隆推送时，需要 Git 版本 1.9 或更高版本。

Gentoo 仓库的特定配置

为了确保遵循 Gentoo 策略，您应该设置以下配置变量：

git config --local user.name "${YOUR_FULL_NAME}"
# use your @gentoo.org address even if you have a different default
git config --local user.email "${YOUR_NICKNAME}@gentoo.org"

# enable commit and push signing
git config --local user.signingkey "0x${LONG_OPENPGP_KEY_ID}"
git config --local commit.gpgsign 1
git config --local push.gpgsign 1

# prevent implicit merges on 'git pull'
git config --local pull.ff only

将转换后的 CVS 历史记录移植到克隆中

要将转换后的 CVS 历史记录包含在 Git 仓库中，您可以将其移植到仓库中：

git remote add history https://anongit.gentoo.org/git/archive/repo/gentoo-2.git
git fetch history
git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d cvs-final-2015-08-08

完成此操作后，诸如 git log 之类的 Git 命令将包含初始 Git 提交后的历史提交。

提交到 gentoo.git

提交和验证提交

向 Gentoo 仓库提交的推荐方法是使用 pkgdev commit（然后 pkgdev push）。它会自动对正在提交的软件包执行必要的 QA 检查，并具有其他有助于 Gentoo 工作流程的功能。

对于任何其他用例，都需要使用 git commit 和其他 Git 命令。Git 的有效用途包括：

  • 创建跨越多个软件包和/或 Gentoo 仓库多个区域（eclasses、许可证、配置文件等）的提交，
  • 使用其他文件或修复程序修改通过 pkgdev commit 创建的提交，
  • 使用 git rebase 合并通过 pkgdev commit 创建的多个提交。

无论何时不使用 pkgdev 进行提交，您都需要使用 pkgcheck scan --commits 手动验证受提交影响的所有软件包。此外，当手动使用 git 时，您必须使用 -s 或 --signoff 选项以及您的 Git 提交命令，手动签署 源代码版权声明。确保您已阅读并理解实际的声明。

原子提交

尽可能使用原子提交。尝试将您的更改拆分为逻辑提交，尽可能遵守以下三个规则：

  1. 不要在一个提交中包含多个不相关的更改。但是，请确保不要不必要地拆分相关更改。例如，如果版本更新需要更改 ebuild，则在一个提交中执行它们是正确的。但是，如果您正在修复先前版本中存在的一个附加错误，则该修复程序应位于单独的提交中。
  2. 在逻辑单元边界处拆分提交。更新多个软件包时，最好每个软件包使用一个提交。避免在一个提交中组合对 ebuild、eclasses、许可证、配置文件等的更改。但是，不要拆分单个软件包中相关的或相互依赖的更改。
  3. 避免创建引入临时损坏的提交。除非不可能，否则按依赖项安装顺序添加软件包。在需要它们的软件包之前添加许可证。在依赖它们的 ebuild 之前提交 package.mask 和其他配置文件更改。通常，将这些更改与添加软件包的提交一起包含也是可以接受的。

请注意，版本更新被视为需要它们的更改的副作用，不应放在单独的提交中。当进行需要版本更新的多个不相关更改时，只需要在由单个推送引入的系列中的第一个提交中更新版本。

Git 提交消息格式

正确格式化提交消息非常重要，以便它们以清晰简洁的方式向读者传达更改。此外，消息格式的一致性允许外部工具更轻松地解析。提交消息的第一行应包含对更改的简要摘要，后跟一个空的新行。从第三行开始，应详细说明提交引入的更改的多行解释。最后，应使用 RFC822/git 样式标签列出辅助信息，例如与提交相关的错误、贡献者和审阅者。应用提交操作时，签署协议也将添加到此处。消息中行的长度应最大为 70-75 个字符。

摘要行应以引用受更改影响的内容开头，后跟冒号“:”字符。根据更改的内容，使用以下列表中的规则确定正确的格式，适当地替换软件包、类别和 eclass 名称：

  • ${CATEGORY}/${PN}: 单个软件包（请注意，pkgdev commit 将自动为您插入此内容）
  • ${CATEGORY}: 软件包类别
  • profiles: 配置文件目录
  • ${ECLASS}.eclass: Eclass 目录
  • licenses: 许可证目录
  • metadata: 元数据目录

对于 ${CATEGORY}/${PN}: 较长的软件包，如果绝对必要，可以超过行长限制，以确保更实用的摘要行。如果一个提交影响多个目录，请在消息前面加上最能反映更改意图的内容。如果 Gentoo Bugzilla 上有任何与提交相关的错误，则可以使用 #nnnnnn 格式将错误的 ID 附加到摘要行。如果您正在修改关键字，请清楚说明添加/删除了哪些关键字。

对于非平凡的提交，消息应包含对提交意图更改的内容、需要它的原因以及如何实现它的详细说明，以及任何其他补充信息。

最后，提交消息应列出辅助信息，例如参与创作、建议、审查和测试更改的人员以及相关的错误。使用 RFC822/git 样式标签，如 Linux 内核补丁指南 中所述。此外，以下标签可选地用于 Gentoo：

  • Bug: 使用此标签引用错误，无需关闭它们。该值是错误的 URL。如果需要引用多个错误，则每个错误都应在单独的 Bug 标签中列出。如果引用了 Gentoo Bugzilla 上的错误，或者 GitHub 上的问题或拉取请求，则会自动添加对提交的引用。

  • Closes: 用于引用 Bug 并自动关闭它们。类似于 Bug:，其值为 Bug 的单个 URL，可以使用多个标签来关闭多个 Bug。如果引用了 Gentoo Bugzilla 上的 Bug，或者 Gentoo 镜像的 GitHub 仓库上的 Issue 或 Pull Request，它将自动关闭（标记为已修复）并引用提交。

提交用户贡献时，请确保在您的提交消息中使用用户的全名和电子邮件地址对其进行署名。请注意并尊重用户的隐私：一些用户希望仅以昵称为人所知。在将此类信息输入提交消息时，请利用 Suggested-by: 或 Reported-by: 等标签。

下面显示了一个提交消息示例

app-misc/foo: version bump to 0.5

This also adds a new USE flag 'bar' which controls the
new bar functionality introduced with this version.

Bug: https://bugs.gentoo.org/00000
Closes: https://bugs.gentoo.org/00001
Signed-off-by: Alice Bar <[email protected]>