• 2025.5.6 重译

• 2024.7.3-2024.7.5 机器翻译完成。

摘要

本文介绍了个人和组织各种参与 FreeBSD 项目的方式。

所以你想参与 FreeBSD 吗？那太好了！FreeBSD 依靠 用户的贡献才能生存。你的参与不仅会得到感谢，它们对于 FreeBSD 持续发展亦至关重要。

来自全球的众多贡献者，涉及各个年龄段和技术领域，都在开发 FreeBSD。要干的活总比能够提供帮助的人更多，一切帮助都将不胜感激。

作为志愿者，你所做的事仅限于你想做的。不过，我们的确希望你能够意识到，FreeBSD 社区中的其他成员对你的期望。在决定是否志愿参与之前，你可能需要考虑这一点。

FreeBSD 项目负责一项完整的操作系统环境，而不单单是一款内核和一些零散的工具。因此，我们的 TODO 列表涵盖了各种各样的任务：从文档编写、Beta 测试和展示，到系统安装器和高度专业化的内核开发。几乎所有技能水平的人，几乎在任何领域，都能为 FreeBSD 做出贡献。

也建议从事与 FreeBSD 相关的商业实体与我们联系。你是否需要一款特殊的扩展来使你的产品正常工作？只要你的请求不过于过分，我们会乐于接受。你是否正在开发一款增值产品？请告知我们！我们可能能够在某些方面合作。自由软件世界正在挑战许多现有的关于软件开发、销售和维护的假设，我们鼓励你至少重新审视它。

1. 需要什么

以下任务和子项目的列表代表了各种 TODO 列表和用户请求的结合体。

1.1. 持续的非程序员任务

许多参与 FreeBSD 的人并不是程序员。项目包括文档编写者、网页设计师和支持人员。这些人所需要做的只是投入时间并愿意学习。

1. 定期阅读 FAQ 和手册。如果发现任何解释不清、含糊不清、过时或错误的内容，请告诉我们。更好的是，给我们提供修正（AsciiDoc 并不难学习，但也可以提交纯文本格式）。

1.2. 持续的程序员任务

这里列出的大多数任务可能需要大量的时间投入、对 FreeBSD 内核的深入了解，或者两者兼备。不过，也有很多适合“周末黑客”的有用任务。

1. 如果你使用 FreeBSD-CURRENT 并且有良好的互联网连接，可以尝试安装 current.FreeBSD.org 上每天生成的完整版本并报告安装过程中遇到的一切失败。

3. 如果你知道某个 bug 修复已成功应用到 -CURRENT，但经过一段合理时间后尚未合并到 -STABLE，请礼貌提醒提交者。

4. 将第三方的软件移到源代码树中的 src/contrib 目录。

5. 确保 src/contrib 中的代码是最新的。

7. 修复那些使用了弃用方法（例如使用 gets() 或包含 malloc.h）的 Port 警告。

8. 如果你参与了任何 Port，并且你做了 FreeBSD 特定的修改，发送你的补丁给原作者（这将使你在他们发布下一个版本时更加方便）。

9. 获取正式标准的副本，如 POSIX®。比较 FreeBSD 的行为与标准要求的行为。如果行为不同，特别是在规范的微妙或晦涩角落，提交问题报告。如果可能，想办法修复它，并在问题报告中附上补丁。如果你认为标准是错的，请向标准化机构提出该问题。

10. 为这个列表建议更多的任务！

1.3. 处理 PR 数据库

从那些尚未分配给其他人的 PR 开始。如果 PR 已分配给其他人，但看起来是你能处理的任务，可以给被分配的人发邮件，询问是否可以继续处理—他们可能已经准备好了补丁，或者有其他想法可以和你讨论。

1.4. 持续的 Port 任务

Port 是一项持续进行中的工作。我们希望为用户提供易于使用、始终保持最新的高质量第三方软件库。我们需要人们捐献一些时间和精力来帮助我们实现这一目标。

所有人都可以参与，并且有许多不同的方式来参与。参与 Port 个是回馈项目的极好的方式。无论你是想要充当持续的角色，还是某个有趣的挑战，我们都很高兴能获得你的帮助！

你可以通过以下几种简单方式为保持 Port 树的更新和良好运作做出贡献：

1.5. 从 Idea 页面选择一个项目

2. 如何参与

对系统的参与通常可以归入以下五类之一或多个：

2.1. Bug 报告和一般评论

• 补丁已经准备好或几乎准备好提交。提交者应该能够在小于 10 分钟额外工作的情况下提交此补丁。

• 它通过了所有 GitHub CI 作业。

• 你可以快速响应反馈。

• 补丁修改的文件数不超过 10 个，且修改行数少于 200 行。大于这个范围的修改可能是可以接受的，或者你可能会被要求将补丁分为多个更小的 RP。

• 所有提交应包含你的名字和有效的电子邮件地址，并按照你希望在 FreeBSD 仓库中看到的方式标记为作者。不能使用虚假的 GitHub 地址。

• Pull request 在审查过程中不应更改范围。如果审查提出的修改会扩展范围，请创建一个独立的 RP。

• 修复提交应与修复的提交合并。你的分支中的每个提交都应该适合 FreeBSD 仓库。

更新 RP 时，请使用强制推送进行 rebase，而不是使用合并提交。更复杂的修改可以作为 RP 提交，但如果它们太大、难以管理、长期无进展、需要进一步讨论或需要大量修订，它们可能会被关闭。请避免创建大而广泛的清理补丁：它们太大且缺乏良好审查所需的重点。错误的补丁可能会被重定向到更合适的讨论场所。

文档团队也接受通过 GitHub 提交的 RP，但尚未为其建立政策。

提交报告后，你应该会收到确认信息和一个追踪号码。请保存此追踪号码，以便更新我们有关问题的详细信息。

2.2. 文档更改

2.3. 修改现有源代码

提交补丁时首选使用统一输出格式，由 diff -u 生成。

% diff -u oldfile newfile

或者

% diff -u -r -N olddir newdir

这将生成给定源文件或目录层次结构的统一差异。

如果你觉得合适（例如，你添加、删除或重命名了文件），可以将你的更改打包成一个 tar 文件。

2.4. 新代码和重要的增量包

在进行大量工作或向 FreeBSD 添加重要新功能的情况下，几乎总是需要将更改作为 tar 文件提交，或上传到 Web 或 FTP 站点供其他人访问。如果你没有 Web 或 FTP 站点的访问权限，可以在合适的 FreeBSD 邮件列表上请求某人来为你托管这些更改。

2.5. 捐赠资金和硬件

我们非常乐意接受捐赠，以推动 FreeBSD 项目的发展，在这样的志愿者项目中，少量的捐赠可以起到很大的作用！硬件捐赠对于扩展我们支持的外设列表也非常重要，因为我们通常没有足够的资金购买这些设备。

2.5.1. 捐赠资金

捐赠可以通过支票方式发送到：

The FreeBSD Foundation
3980 Broadway Street
STE #103-107
Boulder CO 80304
USA

2.5.2. 捐赠硬件

3. 参与 Ports

3.1. 接管未维护的 Ports

3.1.1. 选择未维护的 Port

接管未维护的 Port 是很好的参与方式。未维护的 Port 只有在有人自愿为其工作时才会更新和修复。目前有大量未维护的 Port。建议从接管一个你常用的 Port 开始。

一些 Port 由于其依赖关系和二级 Port 关系，会影响大量其他 Port。通常，我们希望在维护此类 Port 之前，维护者能有一定的经验。

你可以通过查看名为 INDEX 的主 Port 索引，来了解某 Port 是否有依赖关系或二级 Port。（该文件的名称根据 FreeBSD 的版本不同而有所不同；例如，INDEX-13）。一些 Port 有条件依赖关系，这些依赖关系不会包含在默认的 INDEX 构建中。我们希望你通过查看其他 Port 的 Makefile 来识别这些 Port。

3.1.2. 如何接管 Port

你可以随时请求接管任何未维护的 Port。只需将 MAINTAINER 设置为你的电子邮件地址，并发送包含更改的 PR（问题报告）。如果该 Port 有构建错误或需要更新，你可能希望在同一个 PR 中包含其他更改。这将有所帮助，因为许多提交者不太愿意将维护权交给没有 FreeBSD 经验的人员。提交修复构建错误或更新 Port 的 PR 是建立经验记录的最佳途径。

将你的 PR 提交到产品 Ports & Packages。提交者将审查你的 PR，提交更改，并最终关闭 PR。有时这个过程可能需要一些时间（提交者也是志愿者 :)）。

3.2. Port 维护者的挑战

本节将帮助你了解为什么 Port 需要维护，并概述 Port 维护者的责任。

3.2.1. 为什么 Port 需要维护

创建 Port 是一次性的任务。确保 Port 保持最新、能继续构建和运行则需要持续的维护工作。维护者是那些愿意花费部分时间来实现这些目标的人。

Port 需要维护的最主要原因是将最新的第三方软件带给 FreeBSD 社区。另一个挑战是随着 Ports 框架的发展，保持各个 Port 的正常运行。

作为维护者，你需要管理以下挑战：

• 新软件版本和更新。 新版本和现有 Port 软件的更新不断发布，这些需要被纳入 Ports ，以提供最新的软件。

• 依赖关系的变化。 如果你的 Port 的依赖关系发生了重要变化，可能需要更新 Port，以确保它能够继续正常工作。

• 影响依赖 Port 的变化。 如果其他 Port 依赖于你维护的 Port，你对该 Port 的更改可能需要与其他维护者进行协调。

• 与其他用户、维护者和开发者的互动。 成为一个维护者的一部分工作是承担支持角色。你不需要提供一般的支持（但如果你愿意，欢迎提供）。你应该提供的是 FreeBSD 特有问题的协调点。

• 排查 Bug。 Port 可能会受到 FreeBSD 特有 Bug 的影响。当这些 Bug 被报告时，你需要进行调查、找到并修复它们。在它们进入 Ports 之前，彻底测试 Port，找出潜在问题，当然更好。

• Port 基础设施和政策的变化。 有时，构建 Port 和包的系统会进行更新，或者可能会提出新的基础设施建议。你应该关注这些变化，以防你的 Port 受影响，并需要更新。

• 基本系统的变化。 FreeBSD 正在不断开发中。软件、库、内核甚至政策的变化都可能导致 Port 需要相应调整。

3.2.2. 维护者的责任

3.2.2.1. 保持 Port 的更新

本节概述了保持 Port 更新的流程。

1. 关注更新 监控上游供应商的新版本、更新和安全修复。公告邮件列表或新闻网页在这方面很有帮助。有时用户会联系你，询问你的 Port 什么时候更新。如果你忙于其他事情或因任何原因无法及时更新，问问他们是否愿意通过提交更新来帮忙。

   你也可能会收到来自 FreeBSD Ports Version Check 的自动电子邮件，通知你 Port 的 distfile 有更新版本。更多有关该系统的信息（包括如何停止未来的邮件）将在消息中提供。

2. 合并更改 当更新发布时，将这些更改合并到 Port 中。你需要能够生成原始 Port 与更新 Port 之间的补丁。

3. 审查和测试 彻底审查和测试你的更改：

   • 在尽可能多的平台和架构上构建、安装并测试你的 Port。 Port 在一个分支或平台上可能正常工作，但在另一个平台上则会失败。

   • 检查打包列表是否是最新的。包括添加任何新文件和目录，删除未使用的条目。
4. 注意

6. 提供反馈 如果提交者发现你更改中的问题，他们很可能会将其反馈给你。迅速响应可以帮助更快地提交你的 PR，并在解决问题时保持良好的沟通。

7. 最终 你的更改将被提交， Port 将得到更新。PR 会由提交者关闭。就这样！

3.2.2.2. 确保你的 Port 继续正确构建

本节讲述了如何发现和修复导致 Port 无法正确构建的问题。

FreeBSD 仅保证 Ports 在 -STABLE 分支上正常工作。理论上，你应该能够使用每个稳定分支的最新版本（因为 ABI 不应该变化），但如果你能运行该分支，那就更好了。

由于大多数 FreeBSD 安装运行在 PC 兼容机器上（即 i386 架构），我们期望你保持该架构上的 Port 工作。我们希望 Port 也能在 amd64 架构上原生运行。如果你没有这些机器，完全可以请求帮助。

注意

非 x86 机器的常见失败模式是原始程序员假设指针是 int 类型，或者使用了较宽松的旧版 gcc 编译器。越来越多的应用程序作者正在重构他们的代码以消除这些假设，但如果作者没有积极维护代码，你可能需要自己处理这些问题。

以下是确保你的 Port 能够成功构建所需执行的任务：

2. 收集信息 只要意识到存在问题，收集有助于解决问题的信息。由 pkg-fallout 报告的构建错误会附带日志，你可以通过这些日志查看构建失败的位置。如果错误是由用户报告的，请要求他们提供可能帮助诊断问题的信息，例如：

   • 构建日志

   • 用于构建 Port 的命令和选项（包括在 /etc/make.conf 中设置的选项）

   • 他们的 Port 集合上次更新时间

   • 他们的 Port 树和 INDEX 上次更新时间

4. 提交更改 与更新 Port 一样，你现在应该整合更改、进行审查和测试，提交你的更改到 PR 中，并在需要时提供反馈。

5. 将补丁发送给上游作者 在某些情况下，你需要对 Port 做补丁，以使其在 FreeBSD 上运行。有些（但不是所有）上游作者会接受这些补丁并将其合并到下一版本中。如果是这样，这甚至可能帮助他们在其他 BSD 系统上的用户，避免重复劳动。请考虑将适用的补丁作为礼貌发送给作者。

3.2.2.3. 调查与 Port 相关的 bug 报告和 PR

本节讲述了如何发现并修复 bug。

FreeBSD 特有的 bug 通常是由于构建和运行环境的假设不适用于 FreeBSD 所引起的。你不太可能遇到这种问题，但它可能更为微妙且难以诊断。

确保你的 Port 继续按预期工作需要执行的任务如下：

1. 你应在 14 天内回应 PR 和其他报告，但请尽量不要拖延这么长时间。尽早回应，即使只是告知你需要更多时间才能处理 PR。

   如果你 14 天后仍未回应，所有提交者都可以通过 maintainer-timeout 从你未回应的 PR 中提交更改。

2. 收集信息 如果报告 bug 的人没有提供修复方案，你需要收集足够的信息，以便生成一个修复方案。

   如果 bug 是可重现的，你可以自己收集大部分所需的信息。如果无法重现，要求报告 bug 的人提供信息，例如：

   • 他们的操作步骤、预期的程序行为和实际行为的详细描述

   • 用于触发 bug 的输入数据副本

   • 核心转储

   • 堆栈跟踪

3. 消除错误报告 一些 bug 报告可能是错误的。例如，用户可能仅仅是错误地使用了程序；或者他们安装的软件包已经过时，需要更新。有时，报告的 bug 并非 FreeBSD 特有。在这种情况下，将 bug 报告给上游开发者。如果问题是你可以修复的，你还可以给 Port 打补丁，以便在下一次上游发布前应用修复。

4. 找到解决方案 与构建错误一样，你需要找出问题的解决方案。同样，如果遇到困难，记得寻求帮助！

5. 提交或批准更改 与更新 Port 一样，你现在应该整合更改、进行审查和测试，并将你的更改提交到 PR 中（如果问题已经存在 PR，你可以发送后续消息）。如果其他用户已在 PR 中提交了更改，你也可以发送后续消息，告知你是否批准这些更改。

3.2.2.4. 提供支持

作为维护者的一部分，你需要提供支持——不仅是针对软件本身——而是针对 Port 和任何 FreeBSD 特有的奇特问题。用户可能会就问题、建议、问题和补丁联系你。大多数时候，他们的信件将与 FreeBSD 相关。

偶尔，你可能需要展现你的外交技巧，友好地将寻求一般支持的用户指引到合适的资源。较少情况下，你可能会遇到某人询问为什么 RPMS 没有更新，或者如何在 XX Linux 上运行该软件。趁机告诉他们，你的 Port 已经是最新的（如果真是这样的话！），并建议他们尝试使用 FreeBSD。

有时，用户和开发者会认为你是一个忙碌的人，你的时间很宝贵，并且会为你做一些工作。例如，他们可能会：

• 提交一个 PR 或向你发送更新 Port 的补丁，

• 调查并提供对 PR 的修复，或者

• 以其他方式提交对你 Port 的更改。

在这种情况下，你的主要责任是及时回应。再次提醒，非响应维护者的超时期限是 14 天。超过这个期限，未批准的更改可能会被提交。他们为你做了这些工作，因此请尽量及时回应。然后尽快审查、批准、修改或与他们讨论更改。

如果你能够让他们感到他们的贡献受到重视（而且确实应该受到重视），那么你将更有可能说服他们未来为你做更多的事情 :-)。

3.3. 寻找并修复损坏的 Port

有一些非常好的地方可以找到需要关注的 Port。

对于维护的 Port，发送更改也是可以的，但请记得在操作之前询问维护者，看看他们是否已经在处理该问题。

只要你找到了一个 bug 或问题，收集信息、调查并修复它！如果已有 PR，请跟进该 PR。如果没有，请创建新的 PR。你的更改将会被审查，并且如果一切检查无误，将被提交。

3.4. 何时跑路

随着你的兴趣和承诺的变化，你可能会发现自己没有时间继续进行某些（或所有） Port 的贡献。这是可以理解的！如果你不再使用某个 Port 或由于时间或兴趣的变化失去了作为维护者的意愿，请告知我们。这样，我们可以继续让其他人尝试解决现有的 Port 问题，而不必等你的回应。请记住，FreeBSD 是一个志愿者项目，所以如果维护 Port 不再有趣了，可能是时候让别人来接手了！

无论如何， Port 管理团队（portmgr）保留在你长期未积极维护 Port 的情况下重置你的维护权的权利。（目前，这个时间为 3 个月。）我们所说的是，存在未解决的问题或待处理的更新，并且在这段时间内没有得到处理。

3.5. Port 维护者和贡献者的资源

4. 在其他领域入门

在本篇文章中没有提到的领域，你是否正在寻找有趣的开始项目？FreeBSD 项目有多个 Wiki 页面，列出了新贡献者可以获得灵感的领域。

摘要

本文介绍了如何在 FreeBSD 上配置 CUPS。

1. 了解通用 UNIX 打印系统（CUPS）

CUPS（Common UNIX Printing System）为基于 UNIX® 的操作系统提供了一层可移植的打印支持。它由 Easy Software Products 开发，旨在为所有 UNIX® 系统的供应商和用户推广标准的打印解决方案。

CUPS 使用互联网打印协议（IPP）作为管理打印任务和队列的基础。它还支持 Line Printer Daemon（LPD）、Server Message Block（SMB）和 AppSocket（又名 JetDirect）协议，但功能有所简化。CUPS 增加了网络打印机浏览和基于 PostScript 打印机描述（PPD）的打印选项，支持在 UNIX® 环境中进行实际的打印操作。因此，CUPS 非常适合在 FreeBSD、Linux®、Mac OS® X 或 Windows® 的混合环境中共享和访问打印机。

2. 安装 CUPS 打印服务器

要使用预编译的二进制文件安装 CUPS，可以在 root 终端中执行以下命令：

3. 配置 CUPS 打印服务器

安装完成后，需要编辑一些文件来配置 CUPS 服务器。首先，创建或修改文件 /etc/devfs.rules，并添加以下内容，以设置所有潜在打印机设备的正确权限，并将打印机与 cups 用户组关联：

注意

接下来，在 /etc/rc.conf 中添加以下两行：

这两项设置将在启动时启动 CUPS 打印服务器，并调用上述创建的本地 devfs 规则。

为了在某些 Microsoft® Windows® 客户端下启用 CUPS 打印，应该取消注释 /usr/local/etc/cups/mime.types 和 /usr/local/etc/cups/mime.convs 文件中的以下行：

完成这些更改后，必须重新启动 devfs 和 CUPS 系统，可以通过重启计算机或在 root 终端中执行以下两个命令：

4. 配置 CUPS 打印服务器上的打印机

在安装并配置 CUPS 系统后，管理员可以开始配置附加到 CUPS 打印服务器的本地打印机。这一过程与在其他基于 UNIX® 的操作系统（如 Linux® 发行版）上配置 CUPS 打印机非常相似，甚至完全相同。

5. 配置 CUPS 客户端

CUPS 服务器已配置并将打印机添加并发布到网络之后，下一步是配置客户端，即将访问 CUPS 服务器的机器。如果有一台桌面计算机既充当服务器又充当客户端，那么很多信息可能不需要配置。

5.1. UNIX® 客户端

如果 CUPS 客户端难以发现网络上共享的其他 CUPS 打印机，有时可以创建或编辑文件 /usr/local/etc/cups/client.conf，并在其中添加以下条目：

在这种情况下，server-ip 应替换为网络上 CUPS 服务器的本地 IP 地址。

5.2. Windows® 客户端

在 XP 之前的 Windows® 版本中，原生不支持与基于 IPP 的打印机进行网络连接。然而，Windows® XP 及更高版本支持这一功能。因此，在这些版本的 Windows® 中添加 CUPS 打印机非常简单。一般来说，Windows® 管理员会运行 Windows® Add Printer 向导，选择 Network Printer，然后输入以下语法的 URI：

6. CUPS 故障排除

摘要

FreeBSD 项目是一个全球性的、基于志愿者的合作项目，旨在开发一个可移植且高质量的操作系统。FreeBSD 项目以宽松的许可协议发布其产品的源代码，目的是鼓励更多的用户使用其代码。与 FreeBSD 项目合作可以帮助组织减少产品上市时间、降低工程成本，并提高产品质量。

本文探讨了在家电和软件产品中使用 FreeBSD 代码时可能遇到的问题。它突出了 FreeBSD 的一些特性，使其成为产品开发的优秀基础平台。文章最后建议了一些与 FreeBSD 项目合作时的“最佳实践”。

1. 简介

尽管 FreeBSD 的源代码是公开免费的，但为了充分享受该项目成果的好处，组织需要与该项目进行合作。在本文接下来的章节中，我们将讨论与 FreeBSD 项目有效合作的方式，以及在此过程中需要避免的陷阱。

读者警告。 作者认为，本文中列出的 FreeBSD 项目的特点在文章构思和撰写时（2005年）是大致真实的。然而，读者应当意识到，开源社区使用的实践和过程会随着时间的推移发生变化，因此本文中的信息应被视为指示性而非规范性。

1.1. 目标读者

本文适合以下广泛群体：

• 产品公司的决策者，他们希望提高产品质量，减少上市时间，并在长期内降低工程成本。

• 寻找利用“开源”最佳实践的技术顾问。

• 对理解开源项目动态感兴趣的行业观察者。

• 希望使用 FreeBSD 并寻找贡献方式的软件开发者。

1.2. 文章目标

阅读完本文后，你应当能够：

• 理解 FreeBSD 项目的目标及其组织结构。

• 理解其开发模式和发布工程过程。

• 理解传统企业软件开发过程与 FreeBSD 项目中使用的过程有何不同。

• 了解项目使用的通信渠道，以及你可以期待的透明度程度。

• 了解与项目合作的最佳方式——如何有效地减少工程成本、提高上市时间、管理安全漏洞，并在 FreeBSD 项目发展过程中保持与你产品的未来兼容性。

1.3. 文章结构

本文的其余部分结构如下：

2. FreeBSD 作为构建模块集

FreeBSD 是构建产品的优秀基础：

• FreeBSD 项目有着卓越的工程实践，企业可以加以利用。

• 该项目提供了异常透明的工作流程，使得使用其代码的组织可以有效地规划未来。

2.1. 使用 FreeBSD 构建

以下是一些组织使用 FreeBSD 的方式：

• 作为库和工具的上游源代码。 作为该项目的“下游”，企业可以利用上游代码所获得的新特性、错误修复和测试。

• 作为嵌入式操作系统（例如，用于 OEM 路由器和防火墙设备）。在这种模型下，企业使用定制的 FreeBSD 内核和应用程序集，并为设备添加专有的管理层。OEM 可以从 FreeBSD 项目上游添加的新硬件支持中受益，并从基础系统所接受的测试中获益。 FreeBSD 提供了一个自托管的开发环境，允许轻松创建这样的配置。

• 作为高端存储和网络设备管理功能的类 Unix 环境，运行在独立的处理器“刀片”上。 FreeBSD 提供了创建专用操作系统和应用程序镜像的工具。它对 BSD Unix API 的实现已经成熟并经过测试。FreeBSD 还可以为高端设备的其他组件提供稳定的交叉开发环境。

• 作为在其他专有操作系统中支持类 Unix API 的方式，提高其对应用开发者的吸引力。 在这种情况下，FreeBSD 的部分内核和应用程序被“移植”到与其他任务一起运行的专有操作系统中。类 Unix API 实现的可用性可以减少将流行应用程序移植到专有操作系统所需的工作量。由于 FreeBSD 附带了高质量的内部文档，并且具有有效的漏洞管理和发布工程过程，保持系统更新的成本得以保持较低。

2.2. 技术

FreeBSD 项目支持大量的技术，以下是其中的一部分：

• 一个模块化的对称多处理能力内核，具有可加载的内核模块和灵活易用的配置系统。

• 支持以接近机器速度模拟 Linux™ 和 SVR4 二进制文件。支持二进制 Windows™ (NDIS) 网络驱动程序。

• 提供多种编程任务的库：归档工具、FTP 和 HTTP 支持、线程支持，以及完整的 POSIX™ 类编程环境。

• 超过 36000 个移植的应用程序，包括商业和开源软件，通过 FreeBSD 的 Ports 进行管理。

2.3. 组织结构

FreeBSD 的组织结构是非等级化的。

FreeBSD 的贡献者主要分为两类：普通用户和具有写权限的开发者（在术语中称为 committers）。

第一类贡献者有成千上万；绝大多数对 FreeBSD 的贡献来自于这个群体。对代码库的提交权限（写权限）授予那些对项目有持续贡献的个人。获得提交权限的开发者将承担额外的责任，且新提交者会分配导师，以帮助他们学习相关流程。

图 1. FreeBSD 组织结构

冲突解决由一个由九名成员组成的“核心团队”来执行，该团队由提交者选举产生。

2.4. FreeBSD 发布工程流程

• 新特性和破坏性代码进入开发分支，也称为 -CURRENT 分支。

• -STABLE 分支是从 HEAD 定期分支出来的代码线。只有经过测试的代码才能进入 -STABLE 分支。新特性在 -CURRENT 分支中经过测试和稳定后，才允许进入 -STABLE 分支。

• -RELEASE 分支由 FreeBSD 安全团队维护。只有对关键问题的 bug 修复才能进入 -RELEASE 分支。

图 2. FreeBSD 发布分支

代码分支会保持活跃，直到用户和开发者对其仍有兴趣。

3. 与 FreeBSD 协作

像 FreeBSD 这样的开源项目提供了非常高质量的成品代码。

尽管访问优质源代码可以降低初始开发成本，但随着时间的推移，管理变更的成本将开始占主导地位。随着计算环境的变化和新安全漏洞的发现，你的产品也需要改变和适应。使用开源代码最好视为一个 持续过程 而非一次性活动。最适合合作的项目是那些 活跃的 项目；即，拥有活跃社区、明确目标和透明工作风格的项目。

• FreeBSD 拥有一个活跃的开发者社区。截至目前，来自全球每个有人口的大陆的许多贡献者参与其中，且有 300 余名具有提交权限的个人。

• • 为流行的计算机硬件开发一个高质量的操作系统；

  • 并且以宽松的许可证将我们的工作提供给所有人。

3.1. 理解 FreeBSD 文化

为了有效地与 FreeBSD 项目合作，你需要理解该项目的文化。

志愿者驱动的项目与营利性公司运作的规则不同。公司进入开源世界时常犯的一个错误是低估了这些差异。

长期视角。 FreeBSD 的根源可以追溯到近二十年前，加利福尼亚大学伯克利分校计算机科学研究组（CSRG）的工作。[1](FreeBSD 的源代码库包含了自项目创立以来的所有历史记录，并且还有可用的 CD-ROM，里面包含了 CSRG（计算机科学研究组）早期的代码。 ) 一些最初的 CSRG 开发者仍与该项目保持联系。

开发流程。 计算机程序是沟通的工具：在一个层面上，程序员通过精确的符号与工具（编译器）沟通，工具将他们的指令翻译成可执行代码。在另一个层面上，相同的符号用于程序员之间意图的沟通。

变更日志样本

沟通渠道。 FreeBSD 的贡献者遍布全球。电子邮件（以及较少使用的 IRC）是项目中首选的沟通方式。

3.2. 与 FreeBSD 项目合作的最佳实践

接下来，我们来看一些在产品开发中最有效利用 FreeBSD 的最佳实践。

规划长期发展 设置有助于跟踪 FreeBSD 开发进展的流程。例如：

通过 svn blame 生成的注释源代码清单

使用 gatekeeper（门控者）。 任命一名 gatekeeper 来监控 FreeBSD 开发，及时发现可能影响你产品的变化。

利用 FreeBSD 的发布工程努力。 使用来自 -STABLE 开发分支的代码。这些开发分支由 FreeBSD 的发布工程和安全团队正式支持，并且包含经过测试的代码。

捐赠代码以降低成本。 开发产品的主要成本之一是维护工作。通过向项目捐赠非关键代码，你可以使你的代码得到比通常更多的曝光，从而有助于发现更多的 bug、安全漏洞以及性能问题，并且能够被修复。

公开宣传你的参与。 你不必公开宣传你使用 FreeBSD，但这样做有助于你的努力和项目的发展。

让 FreeBSD 社区知道你的公司使用 FreeBSD，有助于提高吸引高质量人才的机会。广泛的支持 FreeBSD 也意味着开发者中对它的关注度更高，这反过来为你的未来奠定了更健康的基础。

4. 结论

FreeBSD 项目的目标是创建并公开一个高质量操作系统的源代码。通过与 FreeBSD 项目的合作，你可以在多个产品开发场景中降低开发成本，并提高上市时间。

我们考察了 FreeBSD 项目的特性，阐明了它为什么是作为组织产品战略一部分的优秀选择。然后，我们探讨了该项目的主流文化，并审视了与其开发者有效互动的方法。本文最后列出了与项目合作时可能有帮助的最佳实践。

参考文献

摘要

这个标题其实只是一个花哨的说法，意味着我将尝试描述整个虚拟内存（VM）体系结构，希望能让每个人都能跟得上。过去一年，我专注于 FreeBSD 中的几个主要内核子系统，其中虚拟内存（VM）和交换（Swap）子系统是最有趣的，NFS 则是“必要的琐事”。我只重写了其中的一小部分代码。在 VM 领域，我唯一的重大重写是交换子系统。我的大部分工作是清理和维护，进行了一些中等程度的代码重写，但在 VM 子系统中并没有进行重大算法调整。VM 子系统的理论基础大部分保持不变，近几年现代化工作的大部分功劳归功于 John Dyson 和 David Greenman。我不是像 Kirk 那样的历史学家，所以不会试图给各种功能打上人物的名字标签，因为我肯定会搞错。

1. 引言

在进入实际设计之前，我们先花点时间讨论一下维护和现代化任何长久存在的代码库的必要性。在编程界，算法往往比代码更为重要，正是由于 BSD 的学术背景，从一开始就对算法设计给予了大量关注。对设计的关注通常会导致一个干净且灵活的代码库，这样的代码库可以随着时间的推移较为容易地修改、扩展或替换。虽然一些人认为 BSD 是一个“老”操作系统，但我们那些在其上工作的人，更倾向于将其视为一个“成熟”的代码库，里面的各种组件被现代化的代码修改、扩展或替换。它已经进化了，而 FreeBSD 无论代码有多老，都处在前沿。这是一个非常重要的区别，而不幸的是，这一点常常被许多人忽略。程序员可能犯的最大错误就是不从历史中学习，而这正是许多其他现代操作系统犯下的错误。Windows NT® 就是一个最好的例子，其后果是灾难性的。Linux 在某种程度上也犯了这个错误——足够多的情况让我们 BSD 人时不时地开一些小玩笑。Linux 的问题其实就是缺乏经验和历史来对比思想，这是一个问题，但 Linux 社区正迅速地解决这个问题，和 BSD 社区解决问题的方式一样——通过持续的代码开发。Windows NT® 的人则不断犯同样的错误，而这些错误在 UNIX® 中早已被解决，他们却要花费数年时间来修复。一遍又一遍。他们有着严重的“非我设计”病和“我们总是对，因为我们的营销部门这么说”这种心态。我对那些无法从历史中学习的人几乎没有容忍度。

FreeBSD 设计中，特别是在 VM/Swap 子系统中的复杂性，很多时候直接源于在各种条件下解决性能问题的需要。这些问题并非由于算法设计不佳，而是由环境因素引起的。在平台之间的直接对比中，当系统资源开始被施压时，这些问题就变得尤为明显。在我描述 FreeBSD 的 VM/Swap 子系统时，读者应该始终牢记两个要点：

1. 性能设计中最重要的方面是“优化关键路径”。性能优化往往会让代码稍微膨胀，以便让关键路径的性能更好。

2. 一个坚实的、通用的设计在长期来看优于一个高度优化的设计。虽然通用设计在最初实现时可能比高度优化的设计慢，但通用设计通常更容易适应变化的条件，而高度优化的设计最终可能需要被丢弃。

任何能够存活并且可以维护多年的代码库，必须从一开始就设计得当，即使这意味着牺牲一些性能。二十年前，人们仍然争论用汇编语言编程比用高级语言编程好，因为前者生成的代码速度是后者的十倍。今天，这个论点的错误已经显而易见——而且这种错误与算法设计和代码通用化之间的相似之处也不言而喻。

2. VM 对象

描述 FreeBSD VM 系统的最佳方式是从用户级进程的角度来看。每个用户进程看到的是一个单一的、私有的、连续的虚拟内存（VM）地址空间，其中包含几种类型的内存对象。这些对象有各种特征。程序代码和程序数据实际上是一个单一的内存映射文件（运行的二进制文件），但程序代码是只读的，而程序数据是写时复制（copy-on-write）的。程序的 BSS 部分只是按需分配并填充为零的内存，称为按需零页填充（demand zero page fill）。任意文件也可以被内存映射到地址空间，这也是共享库机制的工作方式。这样的映射可能需要修改，以保持对进程私有。fork 系统调用在现有复杂度的基础上，进一步增加了 VM 管理的复杂性。

一个程序二进制数据页（它是一个基本的写时复制页）说明了这种复杂性。一个程序二进制文件包含一个预初始化的数据段，这个段最初是直接从程序文件中映射的。当程序被加载到进程的 VM 空间时，这个区域最初是内存映射的，并且由程序二进制文件本身提供支持，允许 VM 系统在之后释放/重用该页，并从二进制文件中重新加载它。然而，待进程修改了这段数据，VM 系统就必须为该进程制作该页的私有副本。由于私有副本已被修改，VM 系统就不能再释放它，因为无法再从原来的二进制文件中恢复它。

你会立即注意到，原本一个简单的文件映射已经变得复杂得多。数据可能是按页修改的，而文件映射是一次性涵盖多页的。当进程执行 fork 时，复杂性进一步增加。当进程 fork 时，结果是两个进程——每个进程都有自己的私有地址空间，包括原始进程在调用 fork() 前所做的任何修改。VM 系统在 fork() 时完全复制数据是不明智的，因为很可能至少有一个进程从此以后只会读取该页，而允许原始页继续使用。原本是私有的页被重新标记为写时复制（copy-on-write），因为每个进程（父进程和子进程）都期望它们自己对 fork 后的修改保持私有，不影响另一个进程。

FreeBSD 用分层的 VM 对象模型来管理这一切。原始的二进制程序文件最终会成为最低层的 VM 对象。在它上面会有一个写时复制层，用来保存那些必须从原始文件复制出来的页。如果程序修改了属于原始文件的数据页，VM 系统会发生一个故障，并在更高层次上复制该页。当进程 fork 时，会推送额外的 VM 对象层。这可能通过一个相对简单的例子来理解。fork() 是所有 *BSD 系统中常见的操作，因此这个例子考虑了一个启动并执行 fork 的程序。当进程启动时，VM 系统创建了一个对象层，我们称之为 A：

A 代表文件——这些页可能根据需要从文件的物理介质中被分页进来和分页出去。对于程序来说，从磁盘分页进是合理的，但我们不希望将其分页出去并覆盖可执行文件。因此，VM 系统创建了第二层 B，这一层将由交换空间（swap space）提供物理支持：

在首次写入该页之后，B 中创建了一个新页，并且其内容从 A 初始化。B 中的所有页都可以被分页进出交换设备。当程序执行 fork() 时，VM 系统会创建两个新的对象层——C1（父进程）和 C2（子进程）——这些层位于 B 之上：

在这个例子中，假设 B 中的一个页被原始父进程修改。进程会发生一个写时复制故障，并在 C1 中复制该页，保持 B 中的原始页不变。现在，假设同一个页在 B 中被子进程修改。进程会发生一个写时复制故障，并在 C2 中复制该页。B 中的原始页现在被完全隐藏，因为 C1 和 C2 都有一份副本，而 B 理论上可以被销毁，如果它不代表一个“真实”的文件；然而，这种优化并不简单，因为它是细粒度的。FreeBSD 并没有进行这种优化。现在，假设（如通常情况那样）子进程执行了 exec()。它的当前地址空间通常会被一个新地址空间替代，该地址空间代表一个新的文件。在这种情况下，C2 层被销毁：

在这种情况下，B 的子进程数量降至 1，所有对 B 的访问现在都通过 C1。这样，B 和 C1 就可以合并在一起。B 中的所有与 C1 共同存在的页在合并过程中会从 B 中删除。因此，尽管前一步的优化没有做出，我们可以在进程退出或执行 exec() 时回收死掉的页。

这个模型会产生一些潜在问题。第一个问题是，你可能会遇到相对深的 VM 对象层次堆栈，这可能会在发生故障时消耗扫描时间和内存。深层堆栈通常发生在进程执行 fork 后又继续 fork（无论是父进程还是子进程）。第二个问题是，你可能会在 VM 对象的深层堆栈中遇到死页，即那些无法访问的页面。在我们最后的例子中，如果父进程和子进程修改了同一个页，它们各自得到自己私有的副本，而 B 中的原始页就不再能被任何人访问。那页就可以从 B 中释放。

FreeBSD 通过一种特殊优化解决了深层堆栈问题，称为“完全被遮蔽情况”（All Shadowed Case）。如果 C1 或 C2 执行足够多的写时复制故障，完全遮蔽了 B 中的所有页，就会发生这种情况。假设 C1 达成了这一点。此时，C1 就可以完全绕过 B，因此，不再是 C1→B→A 和 C2→B→A，而是 C1→A 和 C2→B→A。但看看发生了什么——现在 B 只有一个引用（C2），所以我们可以合并 B 和 C2。最终结果是 B 被完全删除，变成了 C1→A 和 C2→A。通常情况下，B 会包含大量的页，C1 或 C2 并不容易完全遮蔽它。然而，如果我们再次执行 fork 创建一组 D 层，那么 D 层中的一个层就更有可能完全遮蔽 C1 或 C2 所表示的较小数据集。在图中的任何节点进行这种优化都有效，因此即使在一个频繁执行 fork 的机器上，VM 对象堆栈也通常不会变得太深。无论是父进程还是子进程，在执行 fork 或子进程级联 fork 时，情况都一样。

死页问题仍然存在，特别是当 C1 或 C2 没有完全遮蔽 B 时。由于我们的其他优化，这种情况不再是一个大问题，我们允许这些死页存在。如果系统内存不足，它会将这些页交换出去，占用一点交换空间，但这就是问题的全部。

VM 对象模型的优点是 fork() 非常快速，因为不需要实际复制数据。缺点是，你可能会构建一个相对复杂的 VM 对象层，这会稍微减慢页面故障处理速度，并且需要消耗内存来管理 VM 对象结构。FreeBSD 所做的优化已将这些问题减轻到可以忽略的程度，因此没有实际的缺点。

3. SWAP 层

私有数据页最初要么是写时复制页，要么是零填充页。当发生修改并因此需要复制时，原始的后备对象（通常是文件）就无法再用于保存该页的副本，以便当 VM 系统需要将其重新用于其他目的时使用。这时，SWAP 就派上了用场。SWAP 被分配用于为没有其他后备存储的内存提供后备存储。FreeBSD 仅在实际需要时才为 VM 对象分配交换管理结构。然而，交换管理结构在历史上一直存在问题：

• 在 FreeBSD 3.X 版本中，交换管理结构预分配了一个数组，涵盖了所有需要交换后备存储的对象——即使只有该对象的少数几个页面是交换后备的。这在映射了大对象或进程具有较大 RSS（常驻集大小）时会导致内核内存碎片问题。

• 为了跟踪交换空间，内核内存中会保存一个“空洞列表”，这通常也会严重碎片化。由于“空洞列表”是线性列表，交换分配和释放的性能是非最优的 O(n)-每页操作。

• 交换释放过程中需要进行内核内存分配，这会引发低内存死锁问题。

• 由于交错算法（interleaving algorithm）所产生的空洞，这个问题会变得更加严重。

• 此外，交换块映射可能会很容易地变得碎片化，导致非连续的分配。

• 交换操作时，还必须动态分配内核内存用于额外的交换管理结构。

从这个列表可以看出，确实有很多改进空间。对于 FreeBSD 4.X，我对交换子系统进行了完全重写：

• 交换管理结构通过哈希表进行分配，而不是通过线性数组进行分配，这使得它们具有固定的分配大小，并且粒度更加细化。

• 不再使用线性链表来跟踪交换空间预留，现在它使用交换块的位图，位图排列成一棵基数树结构，并且在基数节点结构中有空闲空间的提示。这实际上使得交换分配和释放的操作变成了 O(1) 操作。

• 整个基数树位图也会预分配，以避免在低内存交换操作中分配内核内存。毕竟，系统通常在低内存时进行交换，所以我们应该避免在这些时刻分配内核内存，以避免潜在的死锁问题。

• 为了减少碎片化，基数树能够一次分配大块连续空间，跳过较小的碎片块。

我并没有采取最终的步骤来实现一个“分配提示指针”（allocating hint pointer），该指针将在分配过程中遍历部分交换区，以进一步保证连续的分配，或者至少保证引用的局部性，但我确保了这种添加是可以完成的。

4. 何时释放页面

由于 VM 系统使用所有可用的内存进行磁盘缓存，因此通常很少有真正空闲的页面。VM 系统依赖于能够正确选择未使用的页面，以便重新用于新的分配。选择最优的页面进行释放可能是任何 VM 系统最重要的功能之一，因为如果做出错误的选择，VM 系统可能被迫不必要地从磁盘重新读取页面，从而严重降低系统性能。

我们愿意在关键路径上忍受多少开销，以避免释放错误的页面？每一个错误的选择都会消耗数十万的 CPU 周期，并导致受影响进程明显的停顿，因此我们愿意承受相当大的开销，以确保选择的是正确的页面。这也是 FreeBSD 在内存资源紧张时通常优于其他系统的原因。

空闲页面的确定算法是建立在内存页面使用历史的基础上。为了获取这一历史，系统利用了大多数硬件页面表具有的页面使用位功能。

无论如何，页面使用位会被清除，稍后 VM 系统再次遇到该页面时，发现页面使用位已被设置。这表明该页面仍在被积极使用。如果位仍然清除，则表示该页面没有被积极使用。通过定期测试这个位，物理页面的使用历史（以计数器的形式）就被开发出来。当 VM 系统稍后需要释放一些页面时，检查这个历史成为确定最佳候选页面进行重用的关键。

对于那些没有此功能的平台，系统实际上会模拟一个页面使用位。它会取消映射或保护页面，如果页面再次被访问，则强制发生页面错误。当页面错误发生时，系统简单地标记页面为已使用，并取消保护该页面，以便它可以被使用。虽然仅仅为了确定页面是否被使用而强行触发页面错误看似是一项昂贵的操作，但它比将页面重用为其他用途后发现进程需要该页面并且不得不重新从磁盘获取要便宜得多。

FreeBSD 使用多个页面队列来进一步细化页面重用的选择，并确定何时必须将脏页面刷新到其后备存储。由于 FreeBSD 下的页面表是动态实体，因此从任何使用该页面的进程的地址空间中取消映射页面几乎不需要任何成本。当基于页面使用计数器选择了一个页面候选时，这正是系统所做的。系统必须区分可以理论上随时释放的干净页面和必须先写入其后备存储才能重新使用的脏页面。当找到一个页面候选时，如果该页面是脏的，则将其移到非活动队列；如果是干净的，则将其移到缓存队列。基于脏页面与干净页面的比例，系统会决定何时必须将非活动队列中的脏页面刷新到磁盘。待完成刷新，这些页面将从非活动队列移到缓存队列。此时，缓存队列中的页面仍然可以通过 VM 错误重新激活，且成本相对较低。然而，缓存队列中的页面被认为是“立即可释放的”，并将在系统需要分配新内存时以 LRU（最少最近使用）方式重用。

需要注意的是，FreeBSD VM 系统试图将干净页面与脏页面分开，专门避免不必要的脏页面刷新（这样可以节省 I/O 带宽），并且不会在内存子系统未受到压力时随意移动页面在各个页面队列之间。这就是为什么在执行 systat -vm 命令时，有些系统会看到非常低的缓存队列计数和高的活动队列计数。当 VM 系统的压力增大时，它会更加努力地保持各种页面队列在被认为最有效的水平。

有一个城市传说流传多年，称 Linux 在避免交换页面方面做得比 FreeBSD 更好，但实际上并非如此。实际上发生的情况是，FreeBSD 在主动将未使用的页面换出以腾出更多磁盘缓存空间，而 Linux 则保持未使用的页面在内存中，从而为缓存和进程页面留下了更少的内存。我不知道今天是否仍然如此。

5. 预错误和零填充优化

发生的大部分页面错误都是零填充错误。通过观察 vmstat -s 输出，你通常可以看到这一点。当进程访问其 BSS 区域中的页面时，就会发生这种情况。BSS 区域期望最初为零，但 VM 系统直到进程实际访问它时才会分配内存。当发生错误时，VM 系统不仅需要分配一个新页面，还需要将其填充为零。为了优化零填充操作，VM 系统能够预先将页面填充为零并标记为已零填充，并且在发生零填充错误时请求已零填充的页面。零填充操作发生在 CPU 空闲时，但系统预零填充的页面数量有限，以避免破坏内存缓存。这是一个典型的例子，展示了为了优化关键路径而向 VM 系统中增加复杂性的情况。

6. 页表优化

页表优化是 FreeBSD VM 设计中最具争议的部分，它们随着 mmap() 的广泛使用而显现出一些压力。我认为这实际上是大多数 BSD 系统的特点，尽管我不确定它是何时首次引入的。这里有两项主要优化。首先，硬件页表不包含持久状态，而是可以随时丢弃，只需少量的管理开销。其次，系统中每个活动的页表项都具有一个管理的 pv_entry 结构，该结构与 vm_page 结构相绑定。FreeBSD 可以直接遍历已知存在的映射，而 Linux 必须检查所有 可能 包含特定映射的页表，看看它是否存在，这在某些情况下可能导致 O(n^2) 的开销。正因为如此，FreeBSD 在内存受到压力时往往能够做出更好的页面重用或交换选择，从而在负载下提供更好的性能。然而，FreeBSD 需要内核调优来适应大型共享地址空间的情况，例如在新闻系统中可能会发生的情况，因为它可能会耗尽 pv_entry 结构。

Linux 和 FreeBSD 都在这个领域需要改进。FreeBSD 尝试最大化潜在稀疏活动映射模型的优势（例如并非所有进程都需要映射共享库的所有页面），而 Linux 则在简化算法方面做出了努力。FreeBSD 在这里通常具有性能优势，代价是浪费了一些额外的内存，但 FreeBSD 在处理一个大文件被大量进程共享的情况下表现不佳。另一方面，Linux 在处理许多进程稀疏映射同一共享库的情况时表现不佳，而且在决定页面是否可以重用时也未必优化。

7. 页面着色

最后，我们来讨论页面着色优化。页面着色是一种性能优化，旨在确保对虚拟内存中连续页面的访问最大程度地利用处理器缓存。在古老的时代（即10多年前），处理器缓存通常是映射虚拟内存而非物理内存的。这导致了许多问题，包括在某些情况下必须在每次上下文切换时清空缓存，并且缓存中存在数据别名问题。现代处理器缓存精确地映射物理内存来解决这些问题。这意味着进程地址空间中的两个相邻页面可能并不对应于缓存中的两个相邻页面。实际上，如果不小心，虚拟内存中的相邻页面可能会映射到处理器缓存中的同一页面，从而导致缓存中的数据被提前丢弃，降低 CPU 性能。即便是多路集合相联缓存（尽管效果有所减轻），也会出现这种情况。

FreeBSD 的内存分配代码实现了页面着色优化，意味着内存分配代码将尝试从缓存的角度寻找连续的空闲页面。例如，如果物理内存的第 16 页分配给进程的第 0 页虚拟内存，并且缓存能够容纳 4 页，页面着色代码就不会将物理内存的第 20 页分配给进程的第 1 页虚拟内存。相反，它会分配物理内存的第 21 页。页面着色代码会尽量避免分配第 20 页，因为这会与第 16 页映射到相同的缓存内存，导致缓存不最优。正如你可以想象的那样，这段代码为 VM 内存分配子系统增加了显著的复杂性，但结果是非常值得的。页面着色使得虚拟内存在缓存性能方面与物理内存一样具有确定性。

8. 结论

现代操作系统中的虚拟内存必须高效地处理许多不同的问题，并支持多种使用模式。BSD 系统历来采用的模块化和算法化方法使得我们可以研究并理解当前的实现，并且相对容易地替换掉代码的大部分部分。近年来，FreeBSD 的虚拟内存系统有了许多改进，相关工作仍在继续进行。

9. 奖励问答环节 by Allen Briggs

9.1. 你提到的 FreeBSD 3.X 交换空间的交错算法是什么？

FreeBSD 使用固定的交换交错，默认值为 4。这意味着 FreeBSD 为四个交换区域保留空间，即使你只有一个、两个或三个交换区域。由于交换是交错的，如果你实际上没有四个交换区域，那么表示“这四个交换区域”的线性地址空间就会发生碎片化。例如，如果你有两个交换区域 A 和 B，FreeBSD 对这两个交换区域的地址空间表示将以 16 页为一个块进行交错：

FreeBSD 3.X 使用“连续空闲区域列表”方法来管理空闲交换区域。这个方法的思路是，较大的空闲线性空间可以通过单个列表节点（kern/subr_rlist.c）来表示。但由于碎片化，连续列表最终会变得非常碎片化。在上面的例子中，完全未使用的交换空间将会将 A 和 B 显示为“空闲”，而 C 和 D 显示为“全部分配”。每个 A-B 序列都需要一个列表节点来进行管理，因为 C 和 D 是空洞，不能与下一个 A-B 序列合并。

为什么我们要交错交换空间，而不是直接把交换区域附加到末尾然后做一些更复杂的处理？原因是，在分配线性地址空间时，自动将其交错到多个磁盘上，比尝试将这种复杂性放到其他地方要容易得多。

碎片化会导致其他问题。由于 3.X 系统下它是一个线性列表，而且具有大量固有的碎片化，交换的分配和释放变成了 O(N) 的算法，而不是 O(1) 的算法。再加上一些其他因素（如频繁交换），你就会进入 O(N^2) 和 O(N^3) 级别的开销，这会非常糟糕。在低内存情况下，3.X 系统可能还需要在交换操作过程中分配 KVM 来创建新的列表节点，这可能会导致死锁。

在 4.X 版本中，我们不再使用连续列表，而是使用基数树和交换块的位图来代替范围列表节点。我们虽然在开始时就预分配了所有位图所需的空间，但由于使用了位图（一位代表一个块），而不是使用节点的链表，这样反而节省了更多内存。通过使用基数树而不是线性列表，即使树发生碎片化，性能几乎可以达到 O(1)。

9.2. 清洁页和脏页（非活动页）的分离与在 systat -vm 中看到低缓存队列计数和高活动队列计数的情况有什么关系？systat 的统计数据会将活动页和脏页一起算入活动队列计数吗？

是的，这是令人困惑的。关系在于“目标”与“现实”。我们的目标是将页面分开，但现实情况是，如果系统不在内存紧张的状态下，我们其实不需要特别去分开它们。

这意味着，当系统不受压力时，FreeBSD 不会努力将脏页（非活动队列）和干净页（缓存队列）分开，也不会试图将页从活动队列移动到非活动队列，即使这些页没有被使用。

一个 COW 页面错误可以是零填充的，也可以是程序数据的。无论哪种情况，机制都是一样的，因为支持程序数据的页面几乎可以肯定已经在缓存中。我确实将这两者放在一起讨论。FreeBSD 不会对程序数据或零填充进行预 COW，但它确实会对已经在缓存中的页面进行预映射。

9.4. 在你提到的页面表优化部分，能否提供更多关于 pv_entry 和 vm_page 的细节（或者是否应该是 vm_pmap，如 McKusick、Bostic、Karel 和 Quarterman 在 4.4 版的第 180-181 页所述）？具体来说，什么样的操作/反应会要求扫描这些映射？

一个 vm_page 代表一个（对象，索引号）元组。一个 pv_entry 代表一个硬件页面表项（pte）。例如，如果有五个进程共享同一个物理页面，其中三个进程的页面表实际上映射了该页面，那么这个页面将由一个 vm_page 结构和三个 pv_entry 结构来表示。

pv_entry 结构只代表 MMU 映射的页面（一个 pv_entry 代表一个 pte）。这意味着当我们需要删除一个 vm_page 的所有硬件引用（例如为了重用该页面、将其换出、清空、标记为脏页等）时，我们可以通过扫描与该 vm_page 关联的 pv_entry 链表来删除或修改它们在页面表中的 pte。

在 Linux 中，没有这样的链表。要删除一个 vm_page 的所有硬件页面表映射，Linux 必须索引到每个可能映射该页面的 VM 对象中。例如，如果有 50 个进程都映射了同一个共享库，而你想删除该库中的 X 页面，那么即使只有 10 个进程真正映射了该页面，Linux 也需要索引到这 50 个进程的页面表。因此，Linux 在简化设计的同时牺牲了性能。很多在 FreeBSD 中是 O(1) 或小 N 的虚拟内存算法，在 Linux 中则可能变成 O(N)、O(N^2) 或更差。由于表示一个特定页面的 pte 通常在所有映射了该页面的页面表中位于相同的偏移量，通过减少对页面表的访问（只针对需要修改的 pte）常常能够避免冲掉该偏移量所在的 L1 缓存行，从而提高性能。

FreeBSD 通过增加复杂性（pv_entry 机制）来提高性能（将页面表的访问限制在 仅 需要修改的 pte 上）。

然而，FreeBSD 在这方面存在扩展性问题，Linux 不存在。即使有充足的空闲内存，当数据被大量共享时，FreeBSD 也会面临 pv_entry 结构的数量限制。在这种情况下，即使有足够的内存，仍然可能耗尽 pv_entry 结构。这可以通过在内核配置中增加 pv_entry 结构的数量来解决，但我们仍然需要找到更好的方法。

关于页面表的内存开销与 pv_entry 方案的比较：Linux 使用“不丢弃”的“永久”页面表，但不需要为每个可能映射的 pte 配置一个 pv_entry。FreeBSD 使用“丢弃式”页面表，但为每个实际映射的 pte 添加一个 pv_entry 结构。我认为内存利用率最终差不多，这使得 FreeBSD 在算法上具有优势，因为它能够以非常低的开销随时丢弃页面表。

9.5. 最后，在页面着色部分，可能需要更多描述来解释你在这里的意思。我有些没有理解。

你知道 L1 硬件内存缓存是如何工作的吗？我来解释一下：假设一台机器有 16MB 的主内存，但只有 128K 的 L1 缓存。通常，这个缓存的工作方式是，每个 128K 的主内存块使用相同的 128K 缓存。如果你访问主内存中的 0 偏移地址，然后访问主内存中的 128K 偏移地址，你可能会丢弃从 0 偏移地址读取的数据！

现在，我简化了很多。刚才描述的是所谓的“直接映射”硬件内存缓存。大多数现代缓存是所谓的 2 路组相联缓存或 4 路组相联缓存。组相联方式允许你访问最多 N 个不同的内存区域，这些区域可以共享同一个缓存而不破坏先前缓存的数据。但最多只有 N 个。

因此，如果我有一个 4 路组相联缓存，我可以访问 0 偏移地址、128K 偏移地址、256K 偏移地址和 384K 偏移地址，并且仍然能够再次访问 0 偏移地址并从 L1 缓存中获取。如果我接着访问 512K 偏移地址，然而，缓存中将丢弃四个已缓存的数据对象中的一个。

这非常重要……极其重要，因为处理器的大部分内存访问必须能够从 L1 缓存中获取，因为 L1 缓存以处理器频率运行。只要发生 L1 缓存未命中的情况，必须去 L2 缓存或主内存读取数据，处理器就会停滞，并且可能会浪费数百条指令的时间，等待从主内存读取数据的完成。与现代处理器核心的速度相比，主内存（你在计算机中装的动态 RAM）是 慢 的。

好了，现在说说页面着色：所有现代内存缓存都是所谓的 物理 缓存。它们缓存的是物理内存地址，而不是虚拟内存地址。这使得缓存能够在进程上下文切换时保持不变，这是非常重要的。

但是，在 UNIX® 世界中，你处理的是虚拟地址空间，而不是物理地址空间。你写的任何程序都会看到它被分配的虚拟地址空间。实际上，支持该虚拟地址空间的 物理 页面不一定是物理连续的！事实上，你可能有两个在进程地址空间中相邻的页面，它们可能会位于 物理 内存的 0 偏移地址和 128K 偏移地址。

程序通常假设两个相邻的页面会被最优地缓存。也就是说，你可以在两个页面中访问数据对象，而不会相互覆盖彼此的缓存条目。但这只有在虚拟地址空间下的物理页面是连续的情况下才成立（就缓存而言）。

这就是页面着色的作用。页面着色并不是将 随机 物理页面分配给虚拟地址，这可能会导致不理想的缓存性能，而是将 合理连续 的物理页面分配给虚拟地址。这样，程序可以假设底层硬件缓存的特性与程序直接在物理地址空间中运行时的表现相同。

请注意，我使用了“合理连续”而不是“连续”。从 128K 直接映射缓存的角度来看，物理地址 0 与物理地址 128K 是相同的。因此，你虚拟地址空间中的两个相邻页面，可能会位于物理内存的 128K 偏移地址和 132K 偏移地址，但也很容易位于物理内存的 128K 偏移地址和 4K 偏移地址，并且仍然保持相同的缓存性能特性。所以，页面着色 不 必须将真正连续的物理内存页面分配给连续的虚拟内存页面，它只需要确保从缓存性能和操作的角度来看，分配的页面是连续的。

正在施工

摘要

本文档为 FreeBSD 提交者社区提供信息。所有新的提交者在开始之前应该阅读本文档，现有的提交者也强烈建议定期回顾。

本文档也可能对希望了解 FreeBSD 项目运作方式的社区成员有所帮助。

1. 管理详细信息

有用的链接：

2. FreeBSD 的 OpenPGP 密钥

2.1. 创建密钥

可以使用现有的密钥，但应先通过 documentation/tools/checkkey.sh 检查。此时，确保密钥具有 FreeBSD 用户 ID。

对于那些还没有 OpenPGP 密钥，或者需要新的密钥来符合 FreeBSD 安全要求的人，以下是如何生成一个密钥的步骤。

1. 复制

   # 按优先顺序列出用于签名的首选算法（从强到弱）
   personal-digest-preferences SHA512 SHA384 SHA256 SHA224
   # 新密钥的默认首选项
   default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 CAMELLIA256 AES192 CAMELLIA192 AES CAMELLIA128 CAST5 BZIP2 ZLIB ZIP Uncompressed

2. 生成密钥：

   复制

   % gpg --full-gen-key
   gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc.
   This is free software: you are free to change and redistribute it.
   There is NO WARRANTY, to the extent permitted by law.
   
   Warning: using insecure memory!
   Please select what kind of key you want:
      (1) RSA and RSA (default)
      (2) DSA and Elgamal
      (3) DSA (sign only)
      (4) RSA (sign only)
   Your selection? 1
   RSA keys may be between 1024 and 4096 bits long.
   What keysize do you want? (2048) 2048 ①
   Requested keysize is 2048 bits
   Please specify how long the key should be valid.
   	 0 = key does not expire
         <n>  = key expires in n days
         <n>w = key expires in n weeks
         <n>m = key expires in n months
         <n>y = key expires in n years
   Key is valid for? (0) 3y ②
   Key expires at Wed Nov  4 17:20:20 2015 MST
   Is this correct? (y/N) y
   GnuPG needs to construct a user ID to identify your key.
   
   Real name: Chucky Daemon ③
   Email address: notreal@example.com
   Comment:
   You selected this USER-ID:
   "Chucky Daemon <notreal@example.com>"
   
   Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
   You need a Passphrase to protect your secret key.

• ① 2048 位密钥，三年有效期目前提供足够的保护（2022-10）。

• ② 三年的密钥有效期足够短，以使得计算能力增强后不再使用过时的密钥，但又足够长，以减少密钥管理问题。

• ③ 在此处使用真实姓名，最好与政府签发的 ID 上显示的姓名匹配，以便其他人更容易验证你的身份。在 Comment 部分可以输入一些帮助别人识别你的文字。

新密钥的提交步骤请参见 [committers-guide](crossref:committers-guide)。

3. Kerberos 和 LDAP Web 密码用于 FreeBSD 集群

FreeBSD 集群需要 Kerberos 密码来访问某些服务。由于 LDAP 在集群中代理 Kerberos，Kerberos 密码也作为 LDAP Web 密码。一些需要此密码的服务包括：

要在 FreeBSD 集群中创建一个新的 Kerberos 账户，或使用随机密码生成器重置现有账户的 Kerberos 密码：

% ssh kpasswd.freebsd.org

注意

必须从 FreeBSD.org 集群外部的机器执行此操作。

也可以通过登录 freefall.FreeBSD.org 并运行以下命令手动设置 Kerberos 密码：

% kpasswd

注意

如果之前未使用过 FreeBSD.org 集群的 Kerberos 认证服务，则会显示 Client unknown 错误。此错误意味着必须先使用上面显示的 ssh kpasswd.freebsd.org 方法初始化 Kerberos 账户。

4. 提交权限类型

FreeBSD 仓库包含多个组件，这些组件合并后支持基本操作系统源代码、文档、第三方应用 Port 基础设施和各种维护的工具。当分配 FreeBSD 提交权限时，会指定可以使用该权限的树区域。通常，权限所在的区域反映了谁授权分配该提交权限。以后可能会添加额外的权限区域：当这种情况发生时，提交者应遵循该区域的正常提交权限分配程序，向相关实体寻求批准，并可能在该区域获得一段时间的导师支持。

在开发区域权限概念之前分配的提交权限可能适用于树的许多部分。然而，常识表明，提交者如果未曾在某个区域工作过，应在提交前寻求审查，向适当的责任方寻求批准，并/或与导师合作。由于不同区域的代码维护规则不同，这既有助于提交者在不熟悉的区域工作，也有助于树上的其他人。

鼓励提交者在开发过程中寻求审查，无论工作发生在哪个区域。

4.1. 提交者在其他树区域活动的政策

• 所有提交者都可以修改 src/share/misc/committers-*.dot，src/usr.bin/calendar/calendars/calendar.freebsd 和 ports/astro/xearth/files。

• doc 提交者可以在没有 src 提交者批准的情况下提交文档更改，例如手册页、README 文件、fortune 数据库、日历文件以及注释修复，前提是提交时遵循正常的审查和管理程序。

• 所有提交者都可以在拥有适当权限的非导师提交者批准的情况下对一切其他区域进行更改。导师提交者可以提供 Reviewed by 但不能提供 Approved by。

• 提交者可以通过通常的流程获得附加的权限，寻找导师并由导师向 core、doceng 或 portmgr 提交提案，获批后将被加入到 access 并进入正常的导师期，在此期间会持续提供 Approved by。

4.1.1. 文档隐式（普遍）批准

普遍批准适用于以下类型的修复：

• 错别字

• 微小修复 诸如标点、URL、日期、路径和文件名的错误信息等常见错误，这些错误可能使读者困惑。

多年来，某些隐式批准已经在文档树中获得。这些最常见的情况包括：

5. Git 入门

5.1. Git 基础

本文档假设你已经阅读过这些内容，并尽量不重复基础知识（尽管会简要介绍）。

5.2. Git 简明入门

这份入门指南的范围比旧的 Subversion 入门指南小，但应该涵盖基本的操作。

5.2.1. 范围

如果你想下载 FreeBSD，编译源代码，并通过这种方式保持更新，那么这份指南适合你。它涵盖了获取源代码、更新源代码、二分搜索，并简要讲解如何处理一些本地更改。它主要覆盖基础内容，并在需要时提供深入学习的好指引。当读者觉得基础内容不足时，其他部分的指南会涉及更高级的贡献主题。

5.2.2. 开发者入门

本节介绍了提交者如何推送开发者或贡献者的提交。

5.2.2.1. 日常使用

注意

以下示例中，替换 ${repo} 为所需的 FreeBSD 仓库名称：doc、ports 或 src。

• 克隆仓库：

  复制

  % git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git

  然后你应该会看到官方镜像作为远程源：

  复制

  % git remote -v
  freebsd  https://git.freebsd.org/${repo}.git (fetch)
  freebsd  https://git.freebsd.org/${repo}.git (push)

• 配置 FreeBSD 提交者数据： 在 repo.freebsd.org 上的提交钩子会检查 Commit 字段是否与 FreeBSD.org 上的提交者信息匹配。最简单的方式是通过执行 /usr/local/bin/gen-gitconfig.sh 脚本获取推荐的配置：

  复制

  % gen-gitconfig.sh
  [...]
  % git config user.name (your name in gecos)
  % git config user.email (your login)@FreeBSD.org

• 设置推送 URL：

  复制

  % git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git

  然后你应该会看到分开的 fetch 和 push URL，这是最有效的配置：

  复制

  % git remote -v
  freebsd  https://git.freebsd.org/${repo}.git (fetch)
  freebsd  git@gitrepo.freebsd.org:${repo}.git (push)

  再次注意，gitrepo.freebsd.org 已被规范化为 repo.freebsd.org。

• 安装提交消息模板钩子： 对于 doc 仓库：

  复制

  % cd .git/hooks
  % ln -s ../../.hooks/prepare-commit-msg

  对于 ports 仓库：

  复制

  % git config --add core.hooksPath .hooks

  对于 src 仓库：

  复制

  % cd .git/hooks
  % ln -s ../../tools/tools/git/hooks/prepare-commit-msg

5.2.2.2. admin 分支

access 和 mentors 文件存储在每个仓库的孤立分支 internal/admin 中。

以下是如何将 internal/admin 分支检出到本地名为 admin 的分支的示例：

% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'
% git fetch
% git checkout -b admin internal/admin

或者，你可以为 admin 分支添加一个工作树：

git worktree add -b admin ../${repo}-admin internal/admin

要在 Web 上浏览 internal/admin 分支：<a href="https://cgit.freebsd.org/$%7Brepo%7D/log/?h=internal/admin" class="bare">https://cgit.freebsd.org/${repo}/log/?h=internal/admin</a>

推送时，指定完整的 refspec：

git push freebsd HEAD:refs/internal/admin

5.2.3. 保持与 FreeBSD src 树同步

第一步：克隆树。此操作将下载整个树。下载有两种方式。大多数人会选择对仓库进行深度克隆。但是，有时你可能希望进行浅克隆。

5.2.3.1. 分支名称

FreeBSD-CURRENT 使用 main 分支。

main 是默认分支。

对于 FreeBSD-STABLE，分支名称包括 stable/12 和 stable/13。

对于 FreeBSD-RELEASE，发布工程分支名称包括 releng/12.4 和 releng/13.2。

• main 和 stable/⋯ 分支是开放的

• releng/⋯ 分支在发布标签时会被冻结。

示例：

5.2.3.2. 仓库

注意：该项目不使用子模块，因为子模块与我们的工作流程和开发模型不太契合。如何跟踪第三方应用程序的变化在其他地方有讨论，通常对普通用户来说并不重要。

5.2.3.3. 深度克隆

深度克隆会拉取整个树，以及所有历史和分支。这是最容易操作的方式。它还允许你使用 Git 的 worktree 功能，将所有活跃分支签出到不同的目录，但只有一个仓库副本。

% git clone -o freebsd $URL -b branch [<directory>]

— 这将创建一个深度克隆。branch 应该是前面列出的分支之一。如果没有指定 branch，将使用默认分支 (main)。如果没有指定 <directory>，新目录的名称将与仓库的名称（doc、ports 或 src）匹配。

如果你对历史感兴趣，计划进行本地更改，或者计划在多个分支上工作，那么你会需要一个深度克隆。它也是最容易保持更新的方式。如果你对历史有兴趣，但只在一个分支上工作并且空间有限，你还可以使用 --single-branch 仅下载一个分支（尽管一些合并提交将不会引用已合并的分支，这对某些关注详细历史的用户可能很重要）。

5.2.3.4. 浅克隆

浅克隆仅复制当前的代码，而不会下载历史。这在你需要构建特定版本的 FreeBSD 时非常有用，或者当你刚开始并计划全面跟踪树时。你还可以使用它来限制历史版本的数量。然而，下面会提到这种方法的一个重要限制。

% git clone -o freebsd -b branch --depth 1 $URL [dir]

这将克隆仓库，但只包含最新版本，其余历史不会下载。如果你之后改变主意，可以使用 git fetch --unshallow 来获取旧的历史。

警告

当你进行浅克隆时，uname 输出中将不会显示提交计数。这可能使得在发布安全公告时，判断系统是否需要更新变得更困难。

5.2.3.5. 构建

下载完成后，构建过程按照手册中的描述进行，例如：

% cd src
% make buildworld
% make buildkernel
% make installkernel
% make installworld

因此，这里不再深入讨论。

5.2.3.6. 更新

更新两种类型的树使用相同的命令。这会拉取自上次更新以来的所有修改。

% git pull --ff-only

这将更新树。在 Git 中，"fast forward" 合并是指仅需要设置新的分支指针，而不需要重新创建提交。通过始终执行快速前进合并/拉取，你将确保拥有 FreeBSD 树的准确副本。如果你希望维护本地补丁，这一点非常重要。

见下文如何管理本地更改。最简单的方法是使用 --autostash 选项与 git pull 命令一起使用，但也有更复杂的选项可用。

5.2.4. 选择特定版本

在 Git 中，git checkout 用于检出分支和特定版本。Git 的版本是长哈希值，而不是顺序编号。

当你检出特定版本时，只需在命令行中指定你想要的哈希值（git log 命令可以帮助你决定要选择哪个哈希值）：

% git checkout 08b8197a74

然后你就会检出该版本。你将看到类似如下的消息：

Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.

You are in a 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b <new-branch-name>

HEAD is now at 08b8197a742a hook gpiokeys.4 to the build

其中最后一行是由你检出的哈希值生成的，提交消息的第一行来自该版本的提交。哈希值可以缩写为最短的唯一长度。Git 本身对于显示的数字长度并不一致。

5.2.5. 二分查找（Bisect）

有时，事情出了问题。最后一个版本工作正常，但你刚刚更新的版本不行。开发人员可能会要求你通过二分查找来追踪是哪个提交导致了回归问题。

git bisect start --first-parent 将开始二分查找过程。接下来，你需要告诉 Git 要遍历的版本范围。git bisect good XXXXXX 会告诉它工作版本，git bisect bad XXXXX 会告诉它坏版本。坏版本通常是 HEAD（即你当前检出的版本）。好的版本是你上次检出的版本。--first-parent 参数是必需的，以确保后续的 git bisect 命令不会试图检出缺少完整 FreeBSD 源代码树的供应商分支。

技巧

如果你想知道上次检出的版本，可以使用

复制

5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward
a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main
...

显示我将工作树移动到 main 分支（a816…），然后从上游更新（到 5ef0…）。在这种情况下，坏版本是 HEAD（或 5ef0bd68b515），好版本是 a8163e165c5b。正如你从输出中看到的，HEAD@{1} 通常也有效，但如果在更新后做了其他操作再发现需要进行二分查找时，它并不总是可靠的。

首先设置“好”版本，然后设置“坏”版本（尽管顺序无关紧要）。当你设置坏版本时，它会提供有关过程的统计信息：

% git bisect start --first-parent
% git bisect good a8163e165c5b
% git bisect bad HEAD
Bisecting: 1722 revisions left to test after this (roughly 11 steps)
[c427b3158fd8225f6afc09e7e6f62326f9e4de7e] Fixup r361997 by balancing parens.  Duh.

然后，你需要构建并安装该版本。如果它是好的，输入 git bisect good；如果它是坏的，输入 git bisect bad。如果该版本无法编译，输入 git bisect skip。每一步之后你都会看到类似的消息。完成后，将坏版本报告给开发人员（或自己修复 bug 并提交补丁）。git bisect reset 会结束该过程，并将你带回到你开始的地方（通常是 main 的顶端）。同样，git bisect 手册（如上所述）是处理错误或特殊情况时的良好资源。

5.2.6. 使用 GnuPG 签名提交、标签和推送

Git 知道如何签名提交、标签和推送。当你签名 Git 提交或标签时，你可以证明提交的代码来自你，并且在传输过程中没有被更改。你还可以证明是你提交了代码，而不是别人。

最好的方法是告诉 Git，你总是希望签名提交、标签和推送。你可以通过设置以下几个配置变量来实现：

% git config --add user.signingKey LONG-KEY-ID
% git config --add commit.gpgSign true
% git config --add tag.gpgSign true
% git config --add push.gpgSign if-asked

注意

为了避免可能的冲突，确保给 Git 提供一个长密钥 ID。你可以通过以下命令获得长 ID：gpg --list-secret-keys --keyid-format LONG。

技巧

如果要使用特定的子密钥，而不让 GnuPG 解析为主密钥，可以在密钥后加上 !。例如，要使用子密钥 DEADBEEF 进行加密，使用 DEADBEEF!。

5.2.6.1. 验证签名

提交签名可以通过运行 git verify-commit <commit hash> 或 git log --show-signature 来验证。

标签签名可以通过 git verify-tag <tag name> 或 git tag -v <tag name> 来验证。

5.2.7. Ports 考虑事项

ports 树的操作方式相同，分支名称不同，且仓库的位置也不同。

5.2.7.1. 提交信息格式

提交信息应格式化如下：

category/port: 总结。

描述你为什么做成这些修改。

PR:      12345

重要

第一行是提交的主题，包含了更改的 port 以及提交的总结。它应该包含 50 个字符或更少。

提交信息的其余部分应该在 72 个字符的边界处换行。

应该有一个空行将它与提交信息的其余部分分开。

如果有任何元数据字段，它们应该与提交信息之间有另一个空行，以便容易区分。

5.2.8. 管理本地更改

本节讨论跟踪本地更改。如果你没有本地更改，可以跳过本节。

一个重要的事项是：所有的更改在推送之前都是本地的。与 Subversion 不同，Git 使用的是分布式模型。对于用户而言，大多数操作几乎没有区别。然而，如果你有本地更改，你可以使用相同的工具来管理它们，就像你使用相同的工具来拉取 FreeBSD 的更改一样。所有你尚未推送的更改都是本地的，可以轻松修改（如 git rebase，稍后会讨论）。

5.2.8.1. 保留本地更改

这种方法适用于你对树所做的小改动。当你有一些不那么微小的更改时，最好还是保留一个本地分支并进行 rebase。git stash 也与 git pull 命令集成：只需在命令行上添加 --autostash 即可。

5.2.8.2. 保留本地分支

与 Subversion 不同，Git 保留本地分支更为简便。在 Subversion 中，你需要合并提交并解决冲突。虽然这可以管理，但可能导致历史记录变得复杂，在上游提交时可能困难重重，或者如果你需要重新创建该过程时也很麻烦。Git 也允许合并，存在相同的问题。这是管理分支的一种方式，但它的灵活性最差。

除了合并，Git 还支持“变基”的概念，这可以避免这些问题。git rebase 命令会将一个分支的所有提交重新播放到父分支的新位置。我们将覆盖使用它时最常见的场景。

5.2.8.2.1. 创建分支

假设你想对 FreeBSD 的 ls 命令做一个更改，让它永远不显示颜色。做这个更改有很多原因，但我们用这个作为示例。FreeBSD 的 ls 命令会时不时地更新，你需要应对这些变化。幸运的是，使用 Git rebase 通常是自动完成的。

% cd src
% git checkout main
% git checkout -b no-color-ls
% cd bin/ls
% vi ls.c     # 进行更改
% git diff    # 查看更改
diff --git a/bin/ls/ls.c b/bin/ls/ls.c
index 7378268867ef..cfc3f4342531 100644
--- a/bin/ls/ls.c
+++ b/bin/ls/ls.c
@@ -66,6 +66,7 @@ __FBSDID("$FreeBSD$");
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
+#undef COLORLS
 #ifdef COLORLS
 #include <termcap.h>
 #include <signal.h>
% # 这些更改看起来不错，进行提交...
% git commit ls.c

提交会让你进入编辑器描述你所做的更改。完成后，你就有了一个 本地 分支。按照手册中的说明，像往常一样构建并安装它。Git 与其他版本控制系统的不同之处在于，你必须显式告诉它哪些文件需要提交。我在提交命令行上选择了文件，但你也可以使用 git add 来进行提交，许多更深入的教程会涉及到这一点。

5.2.8.2.2. 更新时

当需要引入新版本时，操作几乎与没有分支时一样。你会像上面那样更新，但在更新之前会有一个额外的命令，在更新后也有一个额外的命令。以下假设你从未修改过树。开始 rebase 操作时，必须确保树是干净的（Git 要求如此）。

% git checkout main
% git pull --ff-only
% git rebase -i main no-color-ls

这会打开一个编辑器，列出所有提交。对于这个示例，不要做任何更改。这通常是在更新基线时所做的（尽管你也可以使用 Git rebase 命令来整理分支中的提交）。

完成上述操作后，你需要将 ls.c 文件中的提交从旧版本的 FreeBSD 移动到新版本中。

有时会出现合并冲突。这是正常的，不用恐慌。你只需像处理任何其他合并冲突一样处理它们。为了简化起见，我将描述一个可能出现的常见问题。完整的处理方式可以在本节末尾找到。

假设包括文件发生了变化，且进行了一个彻底的转换，改用了 terminfo，并且选项名称发生了变化。当你更新时，可能会看到如下内容：

Auto-merging bin/ls/ls.c
CONFLICT (content): Merge conflict in bin/ls/ls.c
error: could not apply 646e0f9cda11... no color ls
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 646e0f9cda11... no color ls

这看起来可能很吓人。如果你打开编辑器，你会看到这是一个典型的三方合并冲突解决方法，你可能已经熟悉了来自其他源代码管理系统的冲突处理（其余的 ls.c 被省略）：

<<<<<<< HEAD
 #ifdef COLORLS_NEW
 #include <terminfo.h>
 =======
 #undef COLORLS
 #ifdef COLORLS
 #include <termcap.h>
 >>>>>>> 646e0f9cda11... no color ls
....

新代码在前，你的代码在后。

正确的修复方法是：在 #ifdef 之前添加 #undef COLORLS_NEW，然后删除旧的更改：

#undef COLORLS_NEW
#ifdef COLORLS_NEW
#include <terminfo.h>
....

保存文件后，rebase 操作被中断，因此你需要完成它：

% git add ls.c
% git rebase --continue
....

这告诉 Git ls.c 已经修复，继续进行 rebase 操作。如果有冲突，你会被带入编辑器来更新提交信息。如果提交信息仍然准确，只需退出编辑器。

如果你在 rebase 时遇到困难，不用恐慌。运行 git rebase --abort 会将你带回到干净的状态。重要的是，开始时树必须是未修改的。顺便说一句，前面提到的 git reflog 在这里非常有用，因为它会列出所有（中间）提交，你可以查看或检查它们，或进行 cherry-pick。

5.2.8.3. 切换到另一个 FreeBSD 分支

如果你希望从 stable/12 切换到当前分支。如果你有一个深度克隆，以下命令即可：

% git checkout main
% # 在此构建并安装...

但是，如果你有本地分支，则有一两个注意事项。首先，rebase 会重写历史，因此你可能需要采取措施保存它。其次，切换分支通常会导致更多的冲突。如果我们假设上述示例相对于 stable/12，然后切换到 main，我建议执行以下操作：

% git checkout no-color-ls
% git checkout -b no-color-ls-stable-12   # 为该分支创建另一个名称
% git rebase -i stable/12 no-color-ls --onto main

上述操作会执行以下步骤：首先检出 no-color-ls 分支。然后创建一个新名称（no-color-ls-stable-12），以防你需要返回它。接着，你将进行 rebase，并将其应用到 main 分支上。这会查找所有当前 no-color-ls 分支中的提交（直到与 stable/12 分支合并的地方），然后将它们重新应用到 main 分支上，从而在 main 分支上创建一个新的 no-color-ls 分支（这就是为什么我让你创建一个占位名称）。

5.3. MFC（从当前合并）流程

5.3.1. 概述

MFC 工作流可以总结为 git cherry-pick -x 加 git commit --amend 来调整提交信息。对于多个提交，使用 git rebase -i 将它们压缩到一起并编辑提交信息。

5.3.2. 单个提交 MFC

% git checkout stable/X
% git cherry-pick -x $HASH --edit

对于 MFC 提交，例如供应商导入，你需要为 cherry-pick 操作指定一个父提交。通常情况下，这将是你从中进行 cherry-pick 的分支的“第一个父”：

% git checkout stable/X
% git cherry-pick -x $HASH -m 1 --edit

如果出现问题，你需要通过 git cherry-pick --abort 中止 cherry-pick 操作，或者修复问题后执行 git cherry-pick --continue。

完成 cherry-pick 后，使用 git push 推送。如果由于提交竞争失败而导致错误，使用 git pull --rebase 并重新尝试推送。

5.3.3. MFC 到 RELENG 分支

向需要批准的分支执行 MFC 时需要更加小心。无论是典型的合并操作还是特殊的直接提交，过程相同：

• 首先将合并或直接提交到适当的 stable/X 分支，然后再合并到 releng/X.Y 分支。

• 使用 stable/X 分支中的哈希值执行 MFC 到 releng/X.Y 分支。

• 在提交信息中保留两个 "cherry picked from" 行。

• 在编辑器中确保添加 Approved by: 行。

% git checkout releng/13.0
% git cherry-pick -x $HASH --edit

如果忘记添加 Approved by: 行，可以通过 git commit --amend 编辑提交信息，然后再推送更改。

5.3.4. 多个提交 MFC

% git checkout -b tmp-branch stable/X
% for h in $HASH_LIST; do git cherry-pick -x $h; done
% git rebase -i stable/X
# 将每个提交（除了第一个）标记为 'squash'
# 如果需要，更新提交信息以反映所有提交的元素。
# 确保保留 "cherry picked from" 行。
% git push freebsd HEAD:stable/X

如果由于提交竞争失败而导致推送失败，执行 rebase 并重新尝试：

% git checkout stable/X
% git pull
% git checkout tmp-branch
% git rebase stable/X
% git push freebsd HEAD:stable/X

MFC 完成后，你可以删除临时分支：

% git checkout stable/X
% git branch -d tmp-branch

5.3.5. MFC 供应商导入

供应商导入是唯一会在 main 分支中创建合并提交的操作。将合并提交 cherry-pick 到 stable/XX 时会遇到额外的困难，因为合并提交有两个父提交。通常，你会希望选择第一个父提交的差异，因为它是与 main 的差异（尽管也可能有一些例外）。

% git cherry-pick -x -m 1 $HASH

通常这就是你需要的命令。这将告诉 cherry-pick 应用正确的差异。

有一些情况（希望是少数）可能是 main 分支被转换脚本反向合并了。如果是这种情况（虽然我们还没有遇到过这种情况），你应该将上述命令中的 -m 1 改为 -m 2，以获取正确的父提交。操作如下：

% git cherry-pick --abort
% git cherry-pick -x -m 2 $HASH

--abort 会清理第一次失败的尝试。

5.3.6. 重新执行 MFC

如果执行了 MFC 操作并且结果非常糟糕，你希望重新开始，最简单的方式是使用 git reset --hard，如下所示：

% git reset --hard freebsd/stable/12

不过，如果你希望保留某些提交，而舍弃其他提交，使用 git rebase -i 更为合适。

5.3.7. MFC 时的注意事项

在将源代码提交到 stable 和 releng 分支时，我们有以下目标：

• 清晰地区分直接提交与从其他分支合并的提交。

• 避免在 stable 和 releng 分支中引入已知的破坏性更改。

• 允许开发者确定哪些更改已经从一个分支合并到另一个分支，哪些没有。

在 Subversion 中，我们使用以下做法来实现这些目标：

• 使用 MFC 和 MFS 标签来标记从其他分支合并的提交。

• 在合并更改时，将修复提交压缩到主要提交中。

• 记录合并信息，以便 svn mergeinfo --show-revs 可以工作。

在 Git 中，我们需要采用不同的策略来实现相同的目标。本文件旨在定义在使用 Git 合并源代码提交时的最佳实践，以实现这些目标。一般来说，我们更倾向于使用 Git 的原生支持来实现这些目标，而不是强制执行基于 Subversion 模型的做法。

一项通用说明：由于 Git 与 Subversion 存在技术差异，我们将不会在 stable 或 releng 分支中使用 Git“合并提交”（通过 git merge 创建的提交）。相反，当本文件提到“合并提交”时，它指的是最初在 main 分支上创建的提交，并通过某种方式使用 git cherry-pick 被复制或“落地”到 stable 分支，或者从 stable 分支复制到 releng 分支的提交。

5.3.8. 查找合适的哈希以进行 MFC

Git 提供了内建支持，使用 git cherry 和 git log --cherry 命令。这些命令比较提交的原始差异（但不比较其他元数据，如日志消息），以确定两个提交是否相同。当每个提交从 main 分支单独合并到稳定分支时，这些命令非常有效，但如果从 main 分支合并多个提交并将它们合并为一个提交到稳定分支时，这种方法就会失效。为了绕过这些困难，项目广泛使用 git cherry-pick -x 保留所有行，并且正在开发自动化工具以利用这一点。

5.3.9. 提交消息标准

5.3.9.1. 标记 MFC

项目采用了以下标记 MFC 的做法：

• 使用 git cherry-pick 的 -x 标志。这会在提交消息中添加一行，包含合并时原始提交的哈希。由于这是 Git 直接添加的，提交者在合并时不需要手动编辑提交日志。

当合并多个提交时，保留所有的 cherry picked from 行。

5.3.9.2. 是否修剪元数据？

在 Subversion（甚至 CVS）中，并未清晰记录如何为 MFC 提交格式化日志消息中的元数据。应该保留原始提交的元数据不变，还是应该修改以反映 MFC 提交本身的信息？

历史做法有所不同，尽管某些差异与字段有关。例如，涉及 PR 的 MFC 通常会在 MFC 中包含 PR 字段，以便将 MFC 提交包含在 bug 跟踪器的审核历史中。其他字段则不太明确。例如，Phabricator 显示的是最后一个提交与评审标签相关的 diff，因此如果在 MFC 中包含 Phabricator URL，会替换主提交为已落地的提交。审查人列表也不明确。如果审查人批准了对 main 的更改，这是否意味着他们也批准了 MFC 提交？如果是完全相同的代码或者仅做了微小修改，那么答案可能是肯定的。但对于更复杂的修改来说，这显然不成立。即使代码完全相同，若提交没有冲突但引入了 ABI 更改，审查人可能会因为 ABI 改变而批准 main 提交，但可能不会批准相同的提交。对此，必须根据具体情况做出判断，直到能够就清晰的指南达成一致。

对于由 re@ 管理的 MFC，增加了新的元数据字段，如 Approved by 标签，用于批准的提交。这些新元数据必须通过 git commit --amend 或类似命令添加，在原始提交经过审核和批准后添加。我们也可能希望将一些元数据字段保留在 MFC 提交中，比如 Phabricator URL，以便将来由 re@ 使用。

保留现有元数据提供了一种非常简单的工作流。开发者使用 git cherry-pick -x，无需编辑日志消息。

如果我们选择调整 MFC 中的元数据，开发者将需要显式地通过使用 git cherry-pick --edit 或 git commit --amend 来编辑日志消息。然而，与 SVN 相比，至少现有的提交消息可以预先填充，并且可以在不重新输入整个提交消息的情况下添加或删除元数据字段。

总的来说，开发者可能需要为非平凡的 MFC 提交整理其提交消息。

5.4. 使用 Git 进行供应商导入

本节详细介绍了使用 Git 进行供应商导入的过程。

5.4.1. 分支命名约定

所有供应商分支和标签都以 vendor/ 开头。这些分支和标签默认是可见的。

注意

本章遵循的约定是，freebsd 为官方 FreeBSD Git 仓库的源名称。如果你使用不同的约定，请在以下示例中将 freebsd 替换为你使用的名称。

我们将以更新 NetBSD 的 mtree 为例，说明其在我们树中的供应商分支。该供应商分支为 vendor/NetBSD/mtree。

5.4.2. 更新旧的供应商导入

供应商树通常只包含适合 FreeBSD 的第三方软件子集。这些树通常比 FreeBSD 树要小得多。因此，Git 工作树非常小且快速，且是推荐使用的方法。确保所选目录（例如 ../mtree）尚不存在。

% git worktree add ../mtree vendor/NetBSD/mtree

5.4.3. 更新供应商分支中的源代码

准备一个完整、干净的供应商源代码树。导入所有内容，但只合并所需的部分。

以下示例假设 NetBSD 源代码已从其 GitHub 镜像克隆到 ~/git/NetBSD。请注意，“上游”可能已经添加或删除了文件，因此我们要确保删除操作也被传播。[net/rsync](https://cgit.freebsd.org/ports/tree/net/rsync/) 通常已安装，因此我将使用它。

% cd ../mtree
% rsync -va --del --exclude=".git" ~/git/NetBSD/usr.sbin/mtree/ .
% git add -A
% git status
...
% git diff --staged
...
% git commit -m "Vendor import of NetBSD's mtree at 2020-12-11"
[vendor/NetBSD/mtree 8e7aa25fcf1] Vendor import of NetBSD's mtree at 2020-12-11
 7 files changed, 114 insertions(+), 82 deletions(-)
% git tag -a vendor/NetBSD/mtree/20201211

至关重要的是验证你正在导入的源代码来自可信的来源。许多开源项目使用加密签名来签署代码更改、Git 标签和/或源代码 tarball。始终验证这些签名，并使用诸如 jail、chroot 等隔离机制，结合一个专用的、非特权用户账户，该账户与你日常使用的账户不同（有关详细信息，请参阅下文的“更新 FreeBSD 源树”部分），直到你确信所导入的源代码是安全的。跟踪上游开发并偶尔检查上游代码更改，有助于提高代码质量并使所有参与者受益。导入到供应商区域之前，检查 git diff 结果也是一个好主意。

始终运行 git diff 和 git status 命令，并仔细检查结果。如有疑问，使用 git annotate 查看供应商分支或上游 Git 仓库，了解是谁做了更改以及为什么。

上面的示例中我们使用了 -m 来说明，但你应该在编辑器中撰写适当的消息（使用提交消息模板）。

同样，重要的是使用 git tag -a 创建一个注解标签，否则推送将被拒绝。只有注解标签才能被推送。注解标签使你有机会输入提交消息，输入你导入的版本以及该版本中的任何重要新特性或修复。

5.4.4. 更新 FreeBSD 副本

此时，你可以将导入的供应商代码推送到我们的仓库中的 vendor 分支。

% git push --follow-tags freebsd vendor/NetBSD/mtree

--follow-tags 告诉 git push 也推送与本地提交版本相关联的标签。

5.4.5. 更新 FreeBSD 源树

现在你需要更新 FreeBSD 中的 mtree。源代码位于 contrib/mtree 目录下，因为它是上游软件。

有时，我们可能需要对贡献的代码进行更改，以更好地满足 FreeBSD 的需求。尽可能地，请尝试将本地更改贡献回上游项目，这有助于它们更好地支持 FreeBSD，也节省了将来导入更新时解决冲突的时间。

% cd ../src
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree

这将生成一个子树合并提交，将 contrib/mtree 与本地的 vendor/NetBSD/mtree 分支合并。检查合并结果的 diff 和上游分支的内容。如果合并减少了本地更改，仅保留了空行或缩进更改等琐碎差异，请尝试修改本地更改以减少与上游的差异，或尝试将剩余的更改贡献回上游项目。如果有冲突，你需要在提交之前解决它们。在合并提交消息中包含有关合并更改的详细信息。

一些开源软件包含 configure 脚本，用于生成定义如何构建代码的文件；通常，这些生成的文件（如 config.h）应在导入过程中更新。在执行此操作时，始终记住这些脚本是在当前用户的凭据下运行的可执行代码。此过程应始终在隔离环境中运行，理想情况下是在没有网络访问权限的 jail 内，并使用非特权账户；或者，至少使用与你日常使用的账户不同的专用账户，这样可以最大限度地减少遇到可能导致数据丢失或更严重的恶意代码的风险。使用隔离的 jail 还可以防止 configure 脚本检测到本地安装的软件包，从而避免出现意外结果。

在测试你的更改时，首先在 chroot 或 jailed 环境中运行，甚至可以先在虚拟机中测试，尤其是对于内核或库的修改。这种方法有助于防止与工作环境发生不良交互。对于许多基本系统组件都使用的库修改，这尤其有益。

5.4.6. 将你的更改与最新的 FreeBSD 源树重新基准化

由于当前的政策建议避免使用合并，如果在你有机会推送之前，FreeBSD 的 main 已经向前移动，那么你将不得不重新执行合并。

常规的 git rebase 或 git pull --rebase 无法像合并提交那样重新基准化，因此你需要重新创建该提交。

以下步骤应帮助你轻松地重新创建合并提交，就好像 git rebase --merge-commits 正常工作一样：

• 进入仓库的顶层目录

• 创建一个包含已合并树内容的旁支 XXX

• 更新旁支 XXX，使其与 FreeBSD 的 main 分支合并并保持最新。

  • 在最坏的情况下，你仍然需要解决合并冲突（如果有的话），但这种情况应该非常罕见。

  • 解决冲突，并在需要时将多个提交压缩为 1 个提交（如果没有冲突，则不需要压缩）

• 切换到 main 分支

• 创建一个分支 YYY（如果出现问题，可以更容易地撤销）

• 重新进行子树合并

• 在子树合并中解决冲突之前，切换到 XXX 分支，将其内容覆盖到当前的 main 分支上。

  • 末尾的 . 是很重要的，且要确保处于仓库的顶层目录。

  • 而不是切换到 XXX 分支，它会将 XXX 的内容覆盖到仓库顶部。

• 使用之前的提交消息提交结果（假设 XXX 分支只有一次合并提交）。

• 确保这两个分支的内容是相同的。

• 根据需要进行任何审查，包括让其他人检查一下，如果你认为这是必要的。

• 推送提交，如果你再次“输掉了比赛”，只需重新执行这些步骤（参见下文的食谱）。

• 提交到上游之后，删除这些分支，它们只是临时的。

以下是使用 mtree 示例时，执行上述操作的命令（# 后面的部分是注释，用于帮助将命令与上面的描述对应起来）：

% cd ../src			# 进入仓库顶层目录
% git checkout -b XXX		# 为合并创建一个新的临时 XXX 分支
% git fetch freebsd		# 获取来自上游的更改
% git merge freebsd/main	# 合并更改并解决冲突
% git checkout -b YYY freebsd/main # 创建一个新的临时 YYY 分支以重新操作
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # 重新进行子树合并
% git checkout XXX .		# XXX 分支包含了解决冲突的内容
% git commit -c XXX~1		# -c 使用重新基准化之前的提交消息
% git diff XXX YYY		# 应该为空
% git show YYY			# 应该只包含你想要的更改，并且是来自供应商分支的合并提交

注意：如果提交出现问题，你可以通过重新执行创建分支的命令，并使用 -B 参数来重置 YYY 分支，以便从头开始：

% git checkout -B YYY freebsd/main # 如果重新开始更容易，可以创建一个新的临时 YYY 分支

5.4.7. 推送更改

当你认为更改已经准备好时，可以将其推送到 GitHub 或 GitLab 上的 fork 以供他人审查。Git 的一个优点是它允许你发布草稿供其他人查看。虽然 Phabricator 很适合内容审查，但发布更新后的供应商分支和合并提交使得其他人可以查看详细信息，因为这些更改最终将出现在仓库中。

经过审查后，当你确信这是一个好的更改时，你可以将其推送到 FreeBSD 仓库：

% git push freebsd YYY:main	# 将提交推送到上游的 'main' 分支
% git branch -D XXX		# 删除临时的 XXX 分支
% git branch -D YYY		# 删除临时的 YYY 分支

注意：我使用 XXX 和 YYY 是为了使它们显得明显，它们是糟糕的名称，应该只在你的机器上使用。如果你将这样的名称用于其他工作，那么你需要选择不同的名称，否则可能会丢失其他工作。这些名称并没有什么神奇之处。上游不会允许你推送它们，但无论如何，请注意上述命令。某些命令的语法与常规用法略有不同，而这种不同的行为对这个食谱的成功至关重要。

5.4.8. 如果需要重做操作

如果你尝试在上一节中进行推送并且失败，那么你应执行以下操作来“重做”事情。这个序列会保持提交消息始终为 XXX~1，以便简化提交过程。

% git checkout -B XXX YYY	# 重新创建临时分支 XXX 并切换到它
% git merge freebsd/main	# 合并更改并解决冲突
% git checkout -B YYY freebsd/main # 重新创建新的临时分支 YYY 以重新操作
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # 重新进行子树合并
% git checkout XXX .		# XXX 分支包含了解决冲突的内容
% git commit -c XXX~1		# -c 重新使用重新基准化之前的提交消息

然后，像之前一样检查并推送。

5.5. 创建一个新的供应商分支

有多种方式可以创建一个新的供应商分支。推荐的方式是创建一个新的仓库，然后将其与 FreeBSD 合并。如果要将 glorbnitz 导入到 FreeBSD 树中，版本为 3.1415。为了简单起见，我们不对该版本进行修剪。它是一个简单的用户命令，可以将 nitz 设备置于不同的魔法 glorb 状态，且其足够小，修剪不会节省太多空间。

5.5.1. 创建仓库

% cd /some/where
% mkdir glorbnitz
% cd glorbnitz
% git init
% git checkout -b vendor/glorbnitz

此时，你已创建了一个新的仓库，所有新的提交都将在 vendor/glorbnitz 分支上进行。

如果你更熟悉，可以直接在 FreeBSD 克隆中执行此操作，使用 git checkout --orphan vendor/glorbnitz。

5.5.2. 将源代码复制进去

由于这是一个新的导入，你可以直接使用 cp、tar 或甚至 rsync 将源代码复制进去，如上所示。假设没有点文件，我们将添加所有内容。

% cp -r ~/glorbnitz/* .
% git add *

此时，你应该有一个干净的 glorbnitz 复制，准备提交。

% git commit -m "Import GlorbNitz frobnosticator revision 3.1415"

5.5.3. 现在将其导入到我们的仓库

现在，你需要将分支导入到我们的仓库。

% cd /path/to/freebsd/repo/src
% git remote add glorbnitz /some/where/glorbnitz
% git fetch glorbnitz vendor/glorbnitz

请注意，vendor/glorbnitz 分支已添加到仓库中。此时，/some/where/glorbnitz 可以删除，如果你愿意的话。它只是为了达到某个目的而存在。

5.5.4. 打标签并推送

从这里开始的步骤与更新供应商分支时类似，只是没有更新供应商分支的步骤。

% git worktree add ../glorbnitz vendor/glorbnitz
% cd ../glorbnitz
% git tag --annotate vendor/glorbnitz/3.1415
# 确保提交正确，可以使用 "git show" 查看
% git push --follow-tags freebsd vendor/glorbnitz

“正确”意味着：

1. 所有正确的文件都存在

2. 没有错误的文件存在

3. 供应商分支指向一个合理的地方

4. 标签看起来很好，且是注释的

5. 标签的提交消息简要概述自上次标签以来的新变化

5.5.5. 最终将其合并到主树中

% cd ../src
% git subtree add -P contrib/glorbnitz vendor/glorbnitz
# 确保提交正常，可以使用 "git show"
% git commit --amend   # 最后的提交消息检查
% git push freebsd

这里“正常”意味着：

1. 所有正确的文件，并且没有错误的文件，已合并到 contrib/glorbnitz 中。

2. 树中没有其他更改。

4. 如果有任何重要的用户可见更改、升级注意事项等，应更新 UPDATING 文件。

注意

这还没有将 glorbnitz 连接到构建中。如何做到这一点取决于被导入的软件，超出了本教程的范围。

5.5.5.1. 保持更新

随着时间的推移，现在是更新树以包含最新的上游更改的时刻。切换到 main 分支时，确保没有差异。在执行以下操作之前，最好先将更改提交到一个分支（或使用 git stash）。

如果你习惯使用 git pull，我们强烈建议使用 --ff-only 选项，并将其设置为默认选项。或者，如果你在 main 分支上有暂存的更改，git pull --rebase 会更有用。

% git config --global pull.ff only

如果你只希望此设置应用于当前仓库，可能需要省略 --global。

% cd freebsd-src
% git checkout main
% git pull (--ff-only|--rebase)

有一个常见的陷阱，git pull 组合命令会尝试执行合并，这有时会创建一个以前不存在的合并提交。这个过程可能更难恢复。

我们也推荐使用更长的命令形式。

% cd freebsd-src
% git checkout main
% git fetch freebsd
% git merge --ff-only freebsd/main

这些命令会将你的树重置为 main 分支，然后从你最初拉取的源更新它。在执行此操作之前，切换到 main 非常重要，这样它才能向前推进。现在，是时候将更改推进：

% git rebase -i main working

5.5.5.2. 将更改推送到上游

首先，确保推送 URL 已正确配置为上游仓库。

% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git

然后，验证你的用户名和电子邮件是否配置正确。我们要求它们与 FreeBSD 集群中的 passwd 条目完全匹配。

在 freefall.freebsd.org 上使用

freefall% gen-gitconfig.sh

可以获得你可以直接使用的配方，前提是 /usr/local/bin 在 PATH 中。

下面的命令会将 working 分支合并到上游的 main 分支。重要的是在执行此操作之前，你要确保你的更改完全符合 FreeBSD 源仓库中的要求。这种语法会将 working 分支推送到 main，将 main 分支推进。只有当这导致 main 的线性更改时（例如，没有合并）时，你才可以执行此操作。

% git push freebsd working:main

如果由于提交竞争导致你的推送被拒绝，请在重新尝试之前重新基准化你的分支：

% git checkout working
% git fetch freebsd
% git rebase freebsd/main
% git push freebsd working:main

5.5.5.3. 将更改推送到上游（替代方法）

有些人发现，在推送到远程仓库之前，将更改合并到本地 main 分支上会更容易。此外，git arc stage 会将更改从分支移到本地 main，当你只需要做分支的子集时。操作与之前部分类似：

% git checkout main
% git merge --ff-only `working`
% git push freebsd

如果你输了比赛，那么再试一次，尝试以下操作：

% git pull --rebase
% git push freebsd

这些命令会获取最新的 freebsd/main，然后将本地的 main 更改基准化到其上，这是当你丢失提交竞争时所需要的。注意：使用此技巧无法合并供应商分支的提交。

5.5.5.4. 查找 Subversion 修订版

% git log

如果你有特定版本，可以使用以下构造命令：

% git log --grep revision=XXXX

这样可以找到特定的修订版。commit 后的十六进制数字是你可以用来引用此提交的哈希值。

5.6. Git 常见问题

本节提供了许多可能会经常出现的问题的针对性答案，适用于用户和开发人员。

注意

我们使用 FreeBSD 仓库的常规约定，源为 freebsd，而不是默认的 origin，以便让人们将其用于自己的开发，并最小化将更改错误推送到错误仓库的风险。

5.6.1. 用户

5.6.1.1. 如何用一个仓库副本跟踪 -current 和 -stable？

Q: 尽管磁盘空间不是大问题，但使用仓库副本更高效。在 SVN 镜像中，我可以从同一个仓库签出多个树。如何用 Git 来实现？

A: 你可以使用 Git 工作树。这里有多种方法可以做到，但最简单的方法是使用克隆来跟踪 -current，并使用工作树来跟踪稳定版本。虽然使用“裸仓库”作为一种应对方法已被提出，但它更为复杂，且不在此文档中介绍。

首先，你需要克隆 FreeBSD 仓库，以下示例中将其克隆到 freebsd-current 以减少混淆。$URL 是适合你的镜像源：

% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' $URL freebsd-current

克隆完成后，你可以简单地从中创建一个工作树：

% cd freebsd-current
% git worktree add ../freebsd-stable-12 stable/12

这将把 stable/12 签出到名为 freebsd-stable-12 的目录，它与 freebsd-current 目录平行。创建后，更新工作树的方式与预期类似：

% cd freebsd-current
% git checkout main
% git pull --ff-only
# 从上游的更改现在已本地化，并且当前树已更新
% cd ../freebsd-stable-12
% git merge --ff-only freebsd/stable/12
# 现在你的 stable/12 也已更新

我建议使用 --ff-only，因为它更安全，可以避免意外进入“合并噩梦”，其中树中会有额外的更改，从而迫使你进行复杂的合并，而不是简单的合并。

5.6.2. 开发人员

5.6.2.1. 哎呀！我不小心提交到了 main 分支，而不是另一个分支。

Q: 有时，我会犯错，不小心提交到了 main 分支。我该怎么办？

A: 首先，不要惊慌。

其次，不要推送。实际上，如果你没有推送，几乎所有问题都可以解决。本节的所有答案假设没有进行推送。

以下解答假设你已经提交到了 main 分支，并且想创建一个名为 issue 的分支：

% git branch issue                # 创建 'issue' 分支
% git reset --hard freebsd/main   # 将 'main' 重置回官方的提交
% git checkout issue              # 回到原先的地方

5.6.2.2. 哎呀！我不小心提交到了错误的分支！

Q: 我正在 wilma 分支上开发一个功能，但不小心在 wilma 中提交了与 fred 分支相关的更改。我该怎么办？

A: 这个解答与之前类似，不过是使用了 cherry-pick。假设 wilma 分支上只有一次提交，但这种方法也可以推广到更复杂的情况。假设这是 wilma 上的最后一次提交（因此使用 wilma 在 git cherry-pick 命令中），但这也可以推广。

# 我们在 wilma 分支上
% git checkout fred		# 切换到 fred 分支
% git cherry-pick wilma		# 拷贝误提交的提交
% git checkout wilma		# 回到 wilma 分支
% git reset --hard HEAD^	# 将 wilma 回退到上一个提交

Git 专家通常会先将 wilma 分支回退 1 次提交，然后切换到 fred，然后使用 git reflog 查看被删除的提交是什么，再将其 cherry-pick 到 fred 分支。

Q: 如果我想将一些更改提交到 main，但出于某些原因保留其余的更改在 wilma 中，怎么办？

A: 上面相同的技巧也适用于你想将当前分支的一部分更改提交到 main，而保留分支其余部分（例如发现了一个不相关的拼写错误或修复了一个偶然的 bug）。你可以将这些更改 cherry-pick 到 main，然后推送到上游仓库。完成后，清理工作也非常简单：只需要使用 git rebase -i。Git 会注意到你已经这样做了，并自动跳过相同的更改（即使你更改了提交消息或稍微调整了提交）。你无需返回 wilma 分支来调整它：只需执行 rebase 操作即可！

Q: 我想将 wilma 分支的一些更改拆分到 fred 分支中，怎么做？

A: 更一般的答案与之前相同。你需要先检出或创建 fred 分支，逐一 cherry-pick 需要的更改，然后对 wilma 分支进行 rebase，移除你已 cherry-pick 到 fred 分支的更改。使用 git rebase -i main wilma 会打开编辑器，你可以删除与 fred 分支中已复制提交对应的 pick 行。如果一切顺利，且没有冲突，那么操作完成。如果遇到冲突，你需要在过程中解决它们。

另一种做法是先检出 wilma，然后创建 fred 分支，使其指向树中的相同位置。然后，你可以对这两个分支执行 git rebase -i，在编辑器中保留要放入 fred 或 wilma 分支的更改 pick 行，删除其他行。一些人会在开始拆分之前创建一个名为 pre-split 的标签/分支，以防拆分过程中出现问题。万一需要撤销拆分操作，可以执行以下步骤：

% git checkout pre-split	# 回到起点
% git branch -D fred		   # 删除 fred 分支
% git checkout -B wilma		# 重置 wilma 分支
% git branch -d pre-split	# 假装什么也没发生

最后一步是可选的。如果你打算重新尝试拆分，你可以省略此步骤。

Q: 但我在阅读时没有看到你的建议，没创建分支，现在 fred 和 wilma 已经完全搞乱了。我该如何找回 wilma 在开始之前的状态？我不知道我做了多少次更改。

A: 一切尚未丢失。只要不久之前做的更改太多（几百次提交的话），你依然可以找回之前的状态。

假设我创建了一个 wilma 分支并提交了一些更改，然后决定将其拆分成 fred 和 wilma。如果在拆分过程中没有出现问题，一切应该顺利。但假设有些不正常的事情发生了，你可以使用 git reflog 来查看做过的更改：

% git reflog
6ff9c25 (HEAD -> wilma) HEAD@{0}: rebase -i (finish): returning to refs/heads/wilma
6ff9c25 (HEAD -> wilma) HEAD@{1}: rebase -i (start): checkout main
869cbd3 HEAD@{2}: rebase -i (start): checkout wilma
a6a5094 (fred) HEAD@{3}: rebase -i (finish): returning to refs/heads/fred
a6a5094 (fred) HEAD@{4}: rebase -i (pick): Encourage contributions
1ccd109 (freebsd/main, main) HEAD@{5}: rebase -i (start): checkout main
869cbd3 HEAD@{6}: rebase -i (start): checkout fred
869cbd3 HEAD@{7}: checkout: moving from wilma to fred
869cbd3 HEAD@{8}: commit: Encourage contributions
...
%

在这里，我们可以看到做过的更改。你可以通过这些信息找出哪里出错了。我想指出几点：首先，HEAD@{X} 是一个“提交点”，因此可以将它作为命令的参数。虽然如果该命令对仓库做了提交操作，X 的数字会发生变化。你也可以使用哈希值（第一列）。

接下来，“Encourage contributions” 是我在决定拆分之前提交到 wilma 的最后一次提交。你也可以看到这个哈希值在我创建 fred 分支时也出现了。我从 fred 开始执行 rebase 操作，可以看到“开始”步骤、每个步骤以及完成步骤。虽然我们在这里不需要这个信息，但它可以帮助你清楚了解发生了什么。幸运的是，修复这个问题的方法是按照之前解答中的步骤执行，但使用哈希值 869cbd3 代替 pre-split。虽然这种方法看起来有点冗长，但由于你是一次处理一件事，记住它很容易。你还可以将操作堆叠在一起：

% git checkout -B wilma 869cbd3
% git branch -D fred

这样，你就准备好重新尝试了。使用 checkout -B 并指定哈希值结合了检出和为其创建分支的操作。使用 -B 而非 -b 会强制移动已经存在的分支。这两种方式都可以使用，这正是 Git 强大（也有时让人头疼）的原因之一。我更倾向于使用 git checkout -B xxxx hash 来避免先检出哈希值后再创建/移动分支，因为那样会出现令人不安的“分离头”状态警告：

% git checkout 869cbd3
M	faq.md
Note: checking out '869cbd3'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b <new-branch-name>

HEAD is now at 869cbd3 Encourage contributions
% git checkout -B wilma

这将产生相同的效果，但我需要阅读更多内容，而“分离头”状态不是我喜欢思考的图像。

5.6.2.4. 混合和匹配分支

问： 我有两个分支 worker 和 async，我想把它们合并成一个名为 feature 的分支，同时保留两个分支中的提交记录，应该怎么做？

答： 这可以通过 cherry pick 来实现。

% git checkout worker
% git checkout -b feature	# 创建一个新的分支
% git cherry-pick main..async	# 将变更引入

现在你就有了一个新的分支 feature。这个分支结合了两个分支的提交。你可以通过 git rebase 进一步修改它。

问： 我有一个名为 driver 的分支，我想将其拆分为 kernel 和 userland，这样我就可以分别独立演进它们，并在每个分支准备好时提交它们。

答： 这需要一些准备工作，但 git rebase 可以完成大部分工作。

% git checkout driver		# 检出 driver 分支
% git checkout -b kernel	# 创建 kernel 分支
% git checkout -b userland	# 创建 userland 分支

现在你有了两个相同的分支。接下来是将提交拆分到这两个分支中的过程。我们假设 driver 中的所有提交都进入 kernel 或 userland，而不是两个分支。

% git rebase -i main kernel

在编辑器中，保留你想要的提交（通过 p 或 pick 行），删除不需要的提交（这看起来很吓人，但如果出错了，你可以通过 driver 分支重新开始，因为你还没有修改它）。

% git rebase -i main userland

对 userland 分支做同样的事。

问： 哇！我按照上述操作了，但忘记了 kernel 分支的一个提交。如何恢复这个提交？

答： 你可以通过 driver 分支找到缺失提交的哈希，并将其 cherry-pick 到 kernel 分支。

% git checkout kernel
% git log driver
% git cherry-pick $HASH

问： 好的。我的情况和上面一样，但我的提交都混在一起了。我需要将一个提交的部分内容放到一个分支，剩余部分放到另一个分支。事实上，我有好几个这样的提交。你提到的选择提交的 rebase 方法看起来有点棘手。

答： 在这种情况下，你最好先整理原始分支，将提交拆分开来，然后使用上述方法将分支拆分。

假设现在只有一个干净的提交。你可以使用 git rebase 中的 edit 选项，或者直接在当前提交上使用该操作。无论哪种方式，步骤都一样。首先，我们需要备份一个提交，并将更改留在工作区：

% git reset HEAD^

注意：此时不要加上 --hard，因为那样会将工作区的更改删除。

现在，如果你幸运的话，需要拆分的更改完全是基于文件的。在这种情况下，你可以像平常一样使用 git add 来将每组文件提交一次。注意：当你执行重置操作时，提交消息会丢失，所以如果需要保存消息，应该先保存一份副本（不过，你可以通过 git log $HASH 恢复提交消息）。

如果不幸运，可能需要将文件拆分开来。这时你可以使用以下工具逐个处理文件：

git add -i foo/bar.c

这将逐步显示差异，并提示你是否包含或排除每个变更块。完成后，使用 git commit 提交剩余的更改。如果有多个文件需要处理，你可以多次运行这个命令，通常我发现一次处理一个文件并使用 git rebase -i 将相关提交合并会更简单些。

5.6.3. 克隆和镜像

问： 我想镜像整个 Git 仓库，怎么做？

答： 如果你只是想镜像仓库，可以使用以下命令：

% git clone --mirror $URL

但如果你希望用它做其他事情，那么你会需要重新克隆仓库。

首先，这会创建一个 "bare 仓库"，即只有仓库数据库，而没有已检出的工作区。这对于镜像非常好，但对于日常工作来说就不太合适了。你可以通过 git worktree 来解决这个问题：

% git clone --mirror https://git.freebsd.org/ports.git ports.git
% cd ports.git
% git worktree add ../ports main
% git worktree add ../quarterly branches/2020Q4
% cd ../ports

但是，如果你不打算将镜像用于进一步的本地克隆，那它就不太适合了。

第二个缺点是，Git 通常会重写上游的引用（如分支名、标签等），使得你的本地引用可以独立于上游发展。这意味着，如果你在该仓库中提交更改，除非是私人项目的分支，否则你会丢失更改。

问： 那我应该怎么办？

答： 你可以将所有上游仓库的引用放入本地仓库的私有命名空间。Git 是通过 'refspec' 来克隆所有内容的，默认的 refspec 是：

fetch = +refs/heads/*:refs/remotes/freebsd/*

这意味着它只会获取分支的引用。

然而，FreeBSD 仓库包含了很多其他内容。你可以为每个引用命名空间添加显式的 refspec，或者选择获取所有内容。要设置你的仓库来执行这一操作：

git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'

这会将上游仓库中的所有内容放入本地仓库的 refs/freebsd/ 命名空间。请注意，这也会获取所有未转换的 vendor 分支，并且它们关联的引用数量非常庞大。

你需要使用完整的名称来引用这些 "refs"，因为它们不在 Git 的常规命名空间中。

git log refs/freebsd/vendor/zlib/1.2.10

上述命令会查看 zlib 的 vendor 分支日志，从 1.2.10 开始。

5.7. 与他人合作

在像 FreeBSD 这样的大型项目中，良好的合作能力是软件开发的关键之一。在 FreeBSD 项目的 Git 仓库中，当前不允许用户创建的分支被推送到仓库中。因此，如果你希望与他人共享你的更改，你必须使用其他机制，例如托管的 GitLab 或 GitHub 来共享用户生成的分支。

以下是如何创建一个基于 FreeBSD main 分支的用户生成分支，并将其推送到 GitHub 的步骤。

% git remote -v
freebsd https://git.freebsd.org/src.git (fetch)
freebsd ssh://git@gitrepo.freebsd.org/src.git (push)

然后，在本地系统上添加一个指向你 fork 的远程源：

% git remote add github git@github.com:gvnn3/freebsd-src.git
% git remote -v
github	git@github.com:gvnn3/freebsd-src.git (fetch)
github	git@github.com:gvnn3/freebsd-src.git (push)
freebsd	https://git.freebsd.org/src.git (fetch)
freebsd	ssh://git@gitrepo.freebsd.org/src.git (push)

% git checkout -b gnn-pr2001-fix

在你的分支中进行任何修改。完成后，进行构建和测试，当你准备好与他人合作时，就可以将你的更改推送到托管的分支了。在推送之前，你需要设置适当的上游分支，因为第一次尝试推送到 GitHub 时，Git 会提示你：

% git push github
fatal: The current branch gnn-pr2001-fix has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream github gnn-pr2001-fix

按照 Git 的建议设置推送上游分支后，推送就会成功：

% git push --set-upstream github gnn-feature
Enumerating objects: 20486, done.
Counting objects: 100% (20486/20486), done.
Delta compression using up to 8 threads
Compressing objects: 100% (12202/12202), done.
Writing objects: 100% (20180/20180), 56.25 MiB | 13.15 MiB/s, done.
Total 20180 (delta 11316), reused 12972 (delta 7770), pack-reused 0
remote: Resolving deltas: 100% (11316/11316), completed with 247 local objects.
remote:
remote: Create a pull request for 'gnn-feature' on GitHub by visiting:
remote:      https://github.com/gvnn3/freebsd-src/pull/new/gnn-feature
remote:
To github.com:gvnn3/freebsd-src.git
 * [new branch]                gnn-feature -> gnn-feature
Branch 'gnn-feature' set up to track remote branch 'gnn-feature' from 'github'.

之后对同一分支的更改将默认正确推送：

% git push
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 314 bytes | 1024 bytes/s, done.
Total 3 (delta 1), reused 1 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:gvnn3/freebsd-src.git
   9e5243d7b659..cf6aeb8d7dda  gnn-feature -> gnn-feature

此时，你的工作已推送到 GitHub 上的分支，并且你可以与其他协作者共享该链接。

5.8. 合并 GitHub Pull 请求

本节介绍了如何将提交到 FreeBSD GitHub 镜像库的 GitHub Pull 请求合并到 FreeBSD 仓库。虽然这不是提交补丁的官方方式，但有时通过这种方式提交的修复非常有效，直接将它们合并到提交者的树上，再从那里推送到 FreeBSD 的树上是最简单的做法。类似的步骤也可以用于将其他仓库的分支合并进来。在合并他人的 Pull 请求时，特别需要小心检查所有更改，确保它们和提交时所展示的一致。

% git remote -v
freebsd https://git.freebsd.org/src.git (fetch)
freebsd ssh://git@gitrepo.freebsd.org/src.git (push)
github https://github.com/freebsd/freebsd-src (fetch)
github https://github.com/freebsd/freebsd-src (fetch)

Pull 请求通常很简单：请求只包含一个提交。在这种情况下，可以使用简化的方法，尽管上一节中介绍的方法也可以使用。这里，创建一个分支，将更改 cherry-pick（挑选提交），调整提交信息，进行测试后再推送。示例中使用了 staging 分支，但它可以是任何名称。当有多个提交时，特别是需要进行小调整时，使用 git rebase -i 比 git cherry-pick 更加有效。以下是相关命令的概述：

1. 创建一个分支；

2. cherry-pick Pull 请求中的更改；

3. 测试它；

4. 调整提交信息；

5. 将其合并到 main 分支；

6. 提交 Pull 请求的 GitHub 链接。

% git fetch github pull/$PR/head:staging
% git rebase -i main staging	# 将 staging 分支更新到最新，调整提交信息
<进行必要的测试>
% git checkout main
% git pull --ff-only		# 若时间已过，确保拉取最新的提交
% git checkout main
% git merge --ff-only staging
<再次测试如果需要>
% git push freebsd --push-option=confirm-author

对于复杂的 Pull 请求，如果有多个提交并且有冲突，可以按照以下步骤进行：

1. 检出 Pull 请求 git checkout github/pull/XXX

2. 创建一个分支进行 rebase git checkout -b staging

3. 将 staging 分支 rebase 到最新的 main 分支 git rebase -i main staging

4. 解决冲突并进行必要的测试

5. 将 staging 分支快进合并到 main 分支

6. 最后的 sanity check，确保一切正常

7. 推送到 FreeBSD 的 Git 仓库

这些步骤同样适用于将其他地方开发的分支合并到本地树并提交。

完成 Pull 请求后，使用 GitHub 的 Web 界面关闭它。如果你的 github 原始库是通过 https:// 配置的，那么你只需要 GitHub 账户来关闭该 Pull 请求。

6. 版本控制历史

FreeBSD 源代码仓库在 2008 年 5 月 31 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r179447。源代码仓库在 2020 年 12 月 23 日从 Subversion 转移到 Git。最后一个正式的 SVN 提交是 r368820，第一个正式的 Git 提交哈希是 5ef5f51d2bef80b0ede9b10ad5b0e9440b60518c。

FreeBSD doc/www 仓库在 2012 年 5 月 19 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r38821。文档仓库在 2020 年 12 月 8 日从 Subversion 转移到 Git。最后一个 SVN 提交是 r54737，第一个正式的 Git 提交哈希是 3be01a475855e7511ad755b2defd2e0da5d58bbe。

FreeBSD ports 仓库在 2012 年 7 月 14 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r300894。Ports 仓库在 2021 年 4 月 6 日从 Subversion 转移到 Git。最后一个 SVN 提交是 r569609，第一个正式的 Git 提交哈希是 ed8d3eda309dd863fb66e04bccaa513eee255cbf。

7. 设置、约定与传统

作为一名新开发者，需要做一些准备工作。以下步骤仅适用于已获得提交权限的开发者。如果你没有提交权限，必须由导师来执行这些步骤。

7.1. 对于新提交者

已获得 FreeBSD 仓库提交权限的开发者，必须遵循以下步骤。

• 在提交每个更改之前，先获得导师的批准！

• 所有 src 的提交首先必须提交到 FreeBSD-CURRENT，然后才能合并到 FreeBSD-STABLE。FreeBSD-STABLE 分支必须保持与该分支早期版本的 ABI 和 API 兼容性。不要合并破坏这种兼容性的更改。

新提交者步骤

1. 添加作者条目doc/shared/authors.adoc - 添加作者条目。后续步骤依赖于此条目，缺少此步骤会导致 doc/ 构建失败。这是一个相对简单的任务，但仍然是测试版本控制技能的好方法。

2. doc/shared/contrib-additional.adoc - 删除 记录。条目按名字排序。

3. 添加新闻项doc/website/data/en/news/news.toml - 添加一条记录。参考其他用于宣布新提交者的条目并遵循格式。使用提交权限批准邮件中的日期。

4. 使用 doc/documentation/tools/checkkey.sh 来验证密钥是否符合最低最佳实践标准。

   添加和检查密钥后，将更新后的文件添加到源控制并提交。此文件中的条目按姓氏排序。

   注意

5. 更新导师和学员信息src/share/misc/committers-.dot - 向当前提交者部分添加一条记录，repository 是指 doc、ports 或 src，具体取决于授予的提交权限。

   在底部部分为每个导师/学员关系添加一条记录。

9. 可选：在 Ports 中添加个人信息ports/astro/xearth/files/freebsd.committers.markers 和 src/usr.bin/calendar/calendars/calendar.freebsd - 有些人会在这些文件中为自己添加条目，以显示自己所在的位置或生日日期。

7.2. 对所有人的要求

1. 向其他开发者介绍自己，否则没人知道你是谁，也不知道你在 FreeBSD 中的工作内容。介绍不需要是详尽的传记，只需要写一两段关于你是谁、你计划在 FreeBSD 中做什么以及你的导师是谁的内容。将此邮件发送到 FreeBSD 开发者邮件列表，这样你就可以开始了！

2. 登录到 freefall.FreeBSD.org 并创建一个 /var/forward/user 文件（其中 user 是你的用户名），文件内容包含你希望将邮件转发到的电子邮件地址，邮件地址格式为 你的用户名@FreeBSD.org。此邮件包括所有提交消息以及任何发送到 FreeBSD 提交者邮件列表和 FreeBSD 开发者邮件列表的邮件。由于 freefall 上有些非常大的邮箱可能会在空间不足时未经警告被截断，因此请将其转发或保存到其他地方。

   注意

   如果你的电子邮件系统使用 SPF 严格规则，你应该将 mx2.FreeBSD.org 排除在 SPF 检查之外。

   由于处理垃圾邮件给中央邮件服务器带来的巨大负担，前端服务器会进行一些基本检查，并根据这些检查丢弃一些邮件。目前，唯一的检查是连接主机的 DNS 信息，但这可能会发生变化。一些人把这些检查归咎于导致有效邮件的丢失。要关闭这些检查，可以在 freefall.FreeBSD.org 上创建文件 ~/.spam_lover。

   注意

   不是提交者但又是开发者的用户将无法订阅提交者或开发者邮件列表。订阅关系是依访问权限而定的。

7.2.1. SMTP 访问设置

对于那些愿意通过 FreeBSD.org 基础设施发送电子邮件的人，请按照以下说明操作：

1. 将邮件客户端指向 smtp.FreeBSD.org:587。

2. 启用 STARTTLS。

3. 确保你的 From: 地址设置为 你的用户名@FreeBSD.org。

4. 注意

   在输入用户名时不要带 @FreeBSD.org。 注意

   额外说明：

   • 只接受来自 你的用户名@FreeBSD.org 的邮件。如果你已作为某个用户认证，不允许你从另一个用户发送邮件。

   • 将附加一个包含 SASL 用户名的头部：（认证发件人： 用户名）。

   • 该主机对邮件发送有各种速率限制，以减少暴力攻击。

7.2.1.1. 使用本地 MTA 将电子邮件转发到 FreeBSD.org SMTP 服务

也可以使用本地 MTA 将本地发送的邮件转发到 FreeBSD.org 的 SMTP 服务器。

示例 1. 使用 Postfix

要告诉本地 Postfix 实例将来自 你的用户名@FreeBSD.org 的邮件转发到 FreeBSD.org 服务器，可以在 main.cf 文件中添加以下内容：

sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd
smtp_use_tls = yes

在 /usr/local/etc/postfix/relayhost_maps 中创建以下内容：

你的用户名@FreeBSD.org  [smtp.freebsd.org]:587

在 /usr/local/etc/postfix/sasl_passwd 中创建以下内容：

[smtp.freebsd.org]:587          你的用户名:你的密码

如果邮件服务器被其他人使用，你可能希望防止他们从你的地址发送邮件。为此，可以在 main.cf 中添加以下内容：

smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps
smtpd_sender_restrictions = reject_known_sender_login_mismatch

在 /usr/local/etc/postfix/sender_login_maps 中创建以下内容：

你的用户名@FreeBSD.org 你的本地用户名

其中 你的本地用户名 是用于连接到本地 Postfix 实例的 SASL 用户名。

示例 2. 使用 OpenSMTPD

要告诉本地 OpenSMTPD 实例将来自 你的用户名@FreeBSD.org 的邮件转发到 FreeBSD.org 服务器，可以在 smtpd.conf 中添加以下内容：

action "freebsd" relay host smtp+tls://freebsd@smtp.freebsd.org:587 auth <secrets>
match from any auth 你的本地用户名 mail-from "_你的用户名_@freebsd.org" for any action "freebsd"

其中 你的本地用户名 是用于连接到本地 OpenSMTPD 实例的 SASL 用户名。

在 /usr/local/etc/mail/secrets 中创建以下内容：

freebsd	你的用户名:你的密码

示例 3. 使用 Exim

要指示本地 Exim 实例将来自 example@FreeBSD.org 的所有邮件转发到 FreeBSD.org 服务器，可以在 Exim 配置文件 中添加以下内容：

Routers section: (在列表顶部)
freebsd_send:
   driver = manualroute
   domains = !+local_domains
   transport = freebsd_smtp
   route_data = ${lookup {${lc:$sender_address}} lsearch {/usr/local/etc/exim/freebsd_send}}

Transport Section:
freebsd_smtp:
        driver = smtp
  tls_certificate=<local certificate>
  tls_privatekey=<local certificate private key>
  tls_require_ciphers = EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+AESGCM:EECDH:EDH+AESGCM:EDH+aRSA:HIGH:!MEDIUM:!LOW:!aNULL:!eNULL:!LOW:!RC4:!MD5:!EXP:!PSK:!SRP:!DSS
  dkim_domain = <local DKIM domain>
  dkim_selector = <local DKIM selector>
  dkim_private_key= <local DKIM private key>
  dnssec_request_domains = *
  hosts_require_auth = smtp.freebsd.org

Authenticators:
freebsd_plain:
  driver = plaintext
  public_name = PLAIN
  client_send = ^example/mail^examplePassword
  client_condition = ${if eq{$host}{smtp.freebsd.org}}

在 /usr/local/etc/exim/freebsd_send 中创建以下内容：

example@freebsd.org:smtp.freebsd.org::587

7.3. 导师

所有新开发者在前几个月都会被分配一个导师。导师的职责是教导学员项目的规则和约定，并引导他们在开发者社区的初步步骤。导师还需要对学员在这一初期阶段的行为负责。

对于提交者：在没有得到导师批准的情况下，不能提交任何内容。提交信息中必须注明 Approved by: 行，记录导师的批准。

8. 提交前审核

代码审查是提高软件质量的一种方式。以下准则适用于对 src 仓库的 main（-CURRENT）分支的提交。其他分支以及 ports 和 docs 树有各自的审查政策，但这些准则一般适用于需要审查的提交：

• 所有非琐碎的更改应在提交到仓库之前进行审核。

• 审核可以通过电子邮件、Bugzilla、Phabricator 或其他机制进行。尽可能地，审核应当公开进行。

• 负责代码更改的开发者同样负责进行所有必要的与审核相关的更改。

• 代码审查是一个迭代过程，直到补丁准备好提交为止。具体来说，补丁发送到审查之后，在提交前应当收到明确的“看起来不错”反馈。在这点上，只要是明确的，可以采取任何适合的反馈形式。

• 超时不能作为审查的替代。

有时代码审查会比你预期的时间更长，尤其是对于大型功能。加速补丁审查的有效方法包括：

• 审查他人的补丁。如果你提供帮助，其他人也更愿意为你提供帮助；良好的合作关系是我们的货币。

• 提醒补丁。如果它很紧急，提供为什么这个补丁对你来说很重要的理由，并每隔几天提醒一次。如果不紧急，常见的礼貌提醒频率是每周一次。记住，你是在请求其他专业开发者宝贵的时间。

• 在邮件列表、IRC 等平台寻求帮助。其他人可能能够直接帮助你，或者建议合适的审查者。

• 将补丁分解成多个较小的补丁，这些补丁彼此依赖。补丁越小，别人快速审查它的概率越高。在做大范围更改时，从一开始就保持这一思路是有帮助的，因为事后将大改动拆分成小补丁通常很困难。

开发者应当作为审查者和被审查者参与代码审查。如果有人愿意审查你的代码，你也应该回报他人，审查他们的代码。需要注意的是，虽然任何人都可以审查并提供反馈，只有相关领域的专家才能批准更改。这通常是一个经常与相关代码一起工作的提交者。

在某些情况下，可能没有相关领域的专家。在这种情况下，由经验丰富的开发者进行审查并结合适当的测试，通常也是足够的。

9. 提交日志消息

本节提供了一些关于提交日志格式的建议和传统。

9.1. 为什么提交信息很重要？

当你在 Git、Subversion 或其他版本控制系统（VCS）中提交更改时，你需要写一段描述该提交的文本——即提交信息。这个提交信息有多重要？是否应该花费一些精力来撰写它？如果你只是写了“修复了一个 bug”，真的有关系吗？

大多数项目有多个开发者，并且持续了一段时间。提交信息是与其他开发者进行沟通的重要方式，无论是当前开发者还是未来的开发者。

FreeBSD 拥有数百名活跃开发者和数十年的历史，涉及数十万次的提交。在这段时间里，开发者社区逐渐意识到好的提交信息有多么重要；有时候，这些经验是通过痛苦的教训获得的。

提交信息至少有三个目的：

• 与其他开发者沟通 FreeBSD 的提交会生成邮件发送到多个邮件列表。这些邮件包括提交信息和补丁本身的副本。提交信息还可以通过如 git log 等命令查看。这些信息有助于让其他开发者了解正在进行的更改；这些开发者可能希望测试该更改、对该主题有兴趣并希望更详细地审查，或者正在进行的项目可能会受益于与之的互动。

• 使更改可发现 在一个拥有悠久历史的大型项目中，当调查某个问题或行为变化时，可能很难找到相关的更改。详细且冗长的提交信息可以使搜索与之相关的更改变得容易。例如，使用 git log --since 1year --grep 'USB timeout' 可以查找相关的历史更改。

• 提供历史文档 提交信息为未来的开发者提供了更改的文档，也许是多年或几十年后。未来的开发者甚至可能是你，作为原作者。当今天看似显而易见的更改，可能在将来就变得不再那么明显了。

git blame 命令会标注源代码文件中的每一行，显示将其引入的更改（哈希值和主题行）。

在明确了提交信息的重要性之后，接下来是一个好的 FreeBSD 提交信息的要素：

9.2. 从主题行开始

提交信息应以一行简短的主题开始，简要总结该更改。主题本身应该允许读者快速判断更改是否值得关注。

9.3. 保持主题行简短

主题行应尽可能简短，同时保留必要的信息。这是为了使浏览 Git 日志更高效，并确保 git log --oneline 能在一个 80 列的行内显示短哈希和主题。一个好的经验法则是保持在 63 个字符以内，并尽可能控制在 50 个字符以内。

9.4. 如果适用，前缀主题行以组件名

如果更改涉及某个特定组件，主题行可以以该组件名称和冒号（:）为前缀。

✓ foo: 添加 -k 选项以保持临时数据

将前缀包含在建议的 63 字符限制内，以便 git log --oneline 不会换行。

9.5. 主题行首字母大写

主题行的首字母应大写。前缀（如果有）除非必要，否则不需要大写（例如，USB: 需要大写）。

9.6. 不要以标点符号结尾

主题行不要以句号或其他标点符号结尾。在这方面，主题行像报纸头条一样。

9.7. 使用空行分隔主题和正文

主题和正文之间应使用空行进行分隔。

一些简单的提交不需要正文，只有主题。

✓ ls: 修复使用文本中的拼写错误

9.8. 限制消息的行宽为 72 列

git log 和 git format-patch 会将提交信息缩进 4 个空格。限制在 72 列内能确保右侧有匹配的边距。将消息限制在 72 个字符以内还能够使提交信息在格式化补丁中低于 RFC 2822 提出的电子邮件行长度限制（78 字符）。这个限制对多种工具有良好的兼容性，避免了较长行长度带来的换行不一致问题。

9.9. 使用现在时，命令式语气

这有助于简短的主题行，并保持一致性，包括自动生成的提交信息（例如，git revert 生成的提交信息）。当阅读一系列提交主题时，这一点尤为重要。将主题视作完成句子“当应用时，该更改将会……”的部分。

✓ foo: 实现 -k（keep）选项 ✗ foo: 实现了 -k 选项 ✗ 该更改在 foo 中实现了 -k 选项 ✗ 添加了 -k 选项

9.10. 聚焦于“做了什么”和“为什么做”，而不是“如何做”

解释更改实现了什么，以及为什么要做这个更改，而不是陈述具体如何实现。

不要假设读者熟悉该问题。解释更改的背景和动机。如果有基准数据，提供这些数据。

如果更改有任何限制或不完整的方面，在提交信息中描述它们。

9.11. 考虑是否可以将提交信息中的某些部分写成代码注释

有时在编写提交信息时，你可能会写下一两句话，解释某些复杂或令人困惑的更改。在这种情况下，考虑是否将这些解释作为代码中的注释，这样它们可以直接帮助未来的开发者（包括你自己）理解代码。

9.12. 为将来的自己编写提交信息

当你为一个更改编写提交信息时，你心中已经掌握了所有相关背景——是什么促使了这次更改，考虑过并拒绝的其他方案、更改的限制等等。想象一下自己在一两年后再次查看这个更改时，写提交信息的方式应该包含所有这些必要的背景信息，以帮助未来的你理解为什么做出这个更改。

9.13. 提交信息应该是自包含的

你可以在提交信息中引用邮件列表帖子、基准测试结果网页或代码审查链接。然而，提交信息应包含所有相关信息，以防这些引用在未来不再可用。

类似地，一个提交可能会引用之前的提交，比如修复 bug 或回退更改的情况。除了提交标识符（修订号或哈希值），还应包括引用提交的主题行（或其他合适的简短引用）。随着每次版本控制系统（VCS）迁移（从 CVS 到 Subversion，再到 Git），早期系统的修订标识符可能变得难以追溯。

9.14. 在脚注中包含适当的元数据

除了在每个提交中包含有意义的消息外，可能还需要附加一些额外的信息。

这些信息由一行或多行构成，每行包含关键字或短语、一个冒号、制表符进行格式化，然后是附加信息。

对于那些可以有多个值的关键字（例如，PR: 后跟以逗号分隔的 PR 列表），可以多次使用相同的关键字，以避免歧义或提高可读性。

关键字或短语如下：

示例 4. 基于 PR 的提交日志

该提交基于 John Smith 提交的 PR 中的补丁。提交消息中的 "PR" 字段已填写。

...

PR:		12345

提交者使用 git commit --author "John Smith <John.Smith@example.com>" 设置补丁的作者。

示例 5. 需要审核的提交日志

虚拟内存系统正在进行更改。补丁已发布到适当的邮件列表（在此案例中为 freebsd-arch），并且更改已获得批准。

...

Reviewed by:	-arch

示例 6. 需要批准的提交日志

提交一个 Port，在与列出的 MAINTAINER 一起工作后，MAINTAINER 允许继续提交。

...

Approved by:	abc (maintainer)

其中 abc 是批准人的账户名。

示例 7. 引入来自 OpenBSD 的代码的提交日志

提交一些基于 OpenBSD 项目工作的代码。

...

Obtained from:	OpenBSD

示例 8. 提交到 FreeBSD-CURRENT 的更改，计划在稍后日期合并到 FreeBSD-STABLE

提交一些代码，该代码将在两周后从 FreeBSD-CURRENT 合并到 FreeBSD-STABLE 分支。

...

MFC after:	2 weeks

其中 2 是计划进行 MFC 的天数、周数或月数。weeks 选项可以是 day、days、week、weeks、month、months。

这些信息常常需要组合在一起。

考虑以下情况：一个用户提交了包含来自 NetBSD 项目的代码的 PR。查看 PR 后，开发人员发现这是他们通常不工作的区域，因此他们让 arch 邮件列表审核了该更改。由于该更改复杂，开发人员决定在一个月后进行 MFC，以便进行充分的测试。

提交中应包含的额外信息如下：

示例 9. 组合提交日志示例

PR:		54321
Reviewed by:	-arch
Obtained from:	NetBSD
MFC after:	1 month
Relnotes:	yes

10. 新文件的首选许可证

FreeBSD 项目建议并使用以下文本作为首选许可证方案：

/*
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * Copyright (c) [year] [your name]
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * [id for your version control system, if any]
 */

FreeBSD 项目强烈不鼓励在新代码中使用所谓的 "广告条款"。由于 FreeBSD 项目有大量的贡献者，对于许多商业供应商来说，遵守该条款变得困难。如果代码中包含广告条款，请考虑将其删除。实际上，请考虑使用上述许可证为你的代码授权。

项目政策要求，某些非 BSD 许可证下的代码只能放置在仓库的特定部分，在某些情况下，编译必须是有条件的，甚至默认禁用。例如，GENERIC 内核必须仅在与 BSD 许可证相同或实质上相似的许可证下编译。GPL、APSL、CDDL 等许可证的软件不得编译到 GENERIC 中。

开发者需注意，在开源中，正确处理 "开源" 和 "源代码" 一样重要，因为不当处理知识产权会带来严重后果。任何问题或疑虑应立即向核心团队报告。

11. 跟踪授予 FreeBSD 项目的许可证

• 授予特殊许可证的个人或组织的联系信息。

• 仓库中哪些文件、目录等受该许可证授权，包括提交的任何特别授权材料的修订号。

• 该许可证生效的日期。除非另有约定，否则此日期应为软件作者授予许可证的日期。

• 许可证文本。

• 适用于 FreeBSD 使用授权材料的任何限制、局限或例外。

• 任何其他相关信息。

12. 树中的 SPDX 标签

截至 2021 年 3 月，树中的大约 25,000 个文件已被标记。

13. 开发者关系

当你在自己的代码上直接工作，或者在已经明确由你负责的代码上工作时，通常无需在提交前与其他提交者进行确认。当你在系统中某个明显无人维护的区域修复 bug（我们为此感到羞愧的确存在一些此类区域）时，同样适用。修改系统中由正式或非正式方式维护的部分时，可以考虑请求审查，就像开发者在成为提交者之前会做的一样。对于 ports，联系 Makefile 中列出的 MAINTAINER。

要判断某个区域是否被维护，可以查看树根目录中的 MAINTAINERS 文件。如果没有列出任何人，请扫描修订历史，查看过去谁提交了更改。要列出过去两年内给定文件的所有提交作者的名字和电子邮件地址，并按提交次数降序排列，可以使用：

% git -C /path/to/repo shortlog -sne --since="2 years" -- relative/path/to/file

如果查询没有得到回应，或者提交者以其他方式表明对该区域缺乏兴趣，可以继续提交。

重要

避免向维护者发送私人邮件。其他人可能对这次对话感兴趣，而不仅仅是最终的结果。

如果对提交有任何疑虑，请在提交之前进行审查。最好在提交前得到批评，而不是等到它已经是仓库的一部分后再遭到批评。如果提交导致争议爆发，可能需要考虑在问题解决之前撤销更改。记住，使用版本控制系统我们总是可以把它恢复回来。

不要诋毁他人的想法。如果他们看到的问题解决方案不同，甚至问题本身不同，可能并不是因为他们愚蠢，或者有可疑的出身，或者他们想摧毁辛勤的工作、个人形象或 FreeBSD，而是因为他们有不同的世界观。和而不同。

诚实地表达分歧。从解决方案的优点出发辩论，诚实地指出其不足，并且愿意以开放的心态看待他们的解决方案，甚至是他们对问题的看法。

接受修正。我们都是容易犯错的。当你犯错时，道歉并继续前进。不要自责，也不要因为错误去责怪别人。不要浪费时间在尴尬或自责上，赶紧修正问题并继续前进。

寻求帮助。寻找（并提供）同行审查。开源软件的一个优势是有更多人参与其中的审查；如果没有人愿意审查代码，那就失去了这一优势。

14. 如果有疑虑……

当你不确定某件事时，无论是技术问题还是项目约定，都要确保向他人请教。如果你保持沉默，你将永远无法取得进展。

如果是技术问题，请在公共邮件列表上提问。避免私下给知道答案的个人发送邮件。这样，所有人都可以从问题和答案中学习。

对于与项目相关的或行政性的问题，请按照以下顺序提问：

• 你的导师或前导师。

• 在 IRC、邮件等平台上的有经验的提交者。

• 任何拥有“帽子”的团队，他们能给你一个权威的答案。

• 如果仍然不确定，可以在 FreeBSD 开发者邮件列表上提问。

如果你的问题得到解答，而且没有人指出有文档明确回答了你的问题，请记录下来，因为其他人也会有同样的问题。

15. Bugzilla

FreeBSD 项目使用 Bugzilla 来追踪 bug 和变更请求。如果你提交了一个修复或建议，并且该内容已经在 PR 数据库中存在，请确保关闭该 PR。如果你有时间，也可以考虑关闭与你的提交相关的其他 PR。

拥有非 FreeBSD.org Bugzilla 账户的提交者，可以通过以下步骤将旧账户与 FreeBSD.org 账户合并：

1. 使用旧账户登录。

2. 打开一个新的 bug，选择 Services 作为产品，选择 Bug Tracker 作为组件。在 bug 诉说中列出你希望合并的账户。

4. 如果要合并的账户超过两个，请从每个账户发布评论。

你可以在以下链接了解更多关于 Bugzilla 的信息：

16. Phabricator

拥有非 FreeBSD.org Phabricator 账户的提交者，可以通过以下步骤将旧账户重命名为 FreeBSD.org 账户：

1. 将你的 Phabricator 账户电子邮件更改为你的 FreeBSD.org 邮件。

重要

Phabricator 账户不能合并，请勿创建新账户。

17. 谁是谁

除了仓库管理者之外，还有其他 FreeBSD 项目成员和团队，你可能会在作为提交者的过程中接触到。简要介绍如下（并非全面列举）：

Konstantin Belousov (kib@FreeBSD.org), Dave Cottlehuber (dch@FreeBSD.org), Marc Fonvieille (blackend@FreeBSD.org), John Hixson (jhixson@FreeBSD.org), Xin Li (delphij@FreeBSD.org), Ed Maste (emaste@FreeBSD.org), Mahdi Mokhtari (mmokhi@FreeBSD.org), Colin Percival (cperciva@FreeBSD.org), Doug Rabson (dfr@FreeBSD.org), Muhammad Moinur Rahman (bofh@FreeBSD.org)：这些成员属于 Release Engineering Team (re@FreeBSD.org)。该团队负责设置发布截止日期和控制发布过程。在代码冻结期间，发布工程师对即将发布版本的系统更改拥有最终权力。如果你希望从 FreeBSD-CURRENT 合并更改到 FreeBSD-STABLE（无论在任何给定时刻这些值为何），这些人是你应该联系的对象。

FreeBSD 提交者邮件列表 {dev-src-all}、{dev-ports-all} 和 {dev-doc-all} 是版本控制系统用来发送提交消息的邮件列表。永远不要直接向这些列表发送邮件。只有在邮件简短且与提交直接相关时，才可以回复这些列表。

FreeBSD 开发者邮件列表：所有提交者都已订阅该列表。这个列表是为提交者的“社区”问题设立的论坛。举例来说，核心投票、公告等。

FreeBSD 开发者邮件列表仅供 FreeBSD 提交者使用。为了开发 FreeBSD，提交者必须能够公开讨论将要解决的问题，直到它们公开发布之前。正在进行中的工作讨论不适合公开发布，否则可能会对 FreeBSD 产生不利影响。

所有 FreeBSD 提交者应确保未经所有作者许可，不将 FreeBSD 开发者邮件列表的消息公开或转发给列表外的人。违规者将被从 FreeBSD 开发者邮件列表中移除，从而暂停提交权限。反复或严重违反者可能会被永久撤销提交权限。

该列表 不是 用于代码审查或任何技术讨论的地方。实际上，使用该列表进行此类讨论会对 FreeBSD 项目造成伤害，因为它给人一种错误印象，认为所有影响到 FreeBSD 使用社区的决策都是在一个封闭的列表中做出的，而没有做到“公开”。最后但同样重要的是 绝对不要 向 FreeBSD 开发者邮件列表发送电子邮件并将其他 FreeBSD 邮件列表作为抄送/密件抄送对象。这样做会极大地削弱该列表的作用。

18. SSH 快速入门指南

2. 重要

   仅支持 ECDSA、Ed25519 或 RSA 密钥。

3. 将你的公钥（$HOME/.ssh/id_ecdsa.pub、$HOME/.ssh/id_ed25519.pub 或 $HOME/.ssh/id_rsa.pub）发送给设置你为提交者的人，以便将其放入 freefall 上的 /etc/ssh-keys/ 目录中的 yourlogin。

通过一个简单的远程命令进行测试：ssh freefall.FreeBSD.org ls /usr。

19. FreeBSD 提交者的 Coverity® 可用性

最后，所有打算使用 Coverity® 的 FreeBSD 开发者都应随时通过向 FreeBSD 开发者的邮件列表提问来获取更多的详细信息和使用信息。

20. FreeBSD 提交者的详细规则清单

1. 尊重其他提交者。

2. 尊重其他贡献者。

3. 在提交之前讨论任何重大更改。

4. 尊重现有的维护者（若在 Makefile 中的 MAINTAINER 字段或顶层目录中的 MAINTAINER 字段中列出）。

5. 如果维护者要求，一切有争议的更改必须在争议解决之前撤回。与安全相关的更改可以在安全官员的裁定下覆盖维护者的意见。

6. 更改应先提交到 FreeBSD-CURRENT，再提交到 FreeBSD-STABLE，除非发布工程师特别允许，或者它们不适用于 FreeBSD-CURRENT。任何非琐碎或非紧急的更改应该在 FreeBSD-CURRENT 中至少等待 3 天，以便进行充分的测试。发布工程师对 FreeBSD-STABLE 分支拥有与规则 #5 中维护者相同的权力。

7. 不要与其他提交者公开争吵；这会显得不好。

8. 尊重所有代码冻结，及时阅读 committers 和 developers 邮件列表，了解何时实施代码冻结。

9. 对于任何程序有疑问时，先询问！

10. 提交更改之前请先进行测试。

11. 在没有 明确 获得相关维护者的批准的情况下，不要提交外部软件。

如上所述，违反这些规则可能会导致暂停提交权限，或者在多次违规后永久撤销提交权限。核心成员有权暂时暂停提交权限，直到核心小组有机会审查该问题。在“紧急情况”（如提交者对代码库造成损害）下，代码库管理员也可以暂时暂停权限。只有 2/3 多数的核心成员有权暂停提交权限超过一周，或永久撤销权限。此规则的存在并不是为了让核心成为一群残酷的独裁者，而是为了给项目提供一种安全保护措施。如果某人失控，能够立即采取行动而不被辩论拖延是非常重要的。在所有情况下，提交者的权限被暂停或撤销时，有权要求由核心进行“听证”，暂停的总时长将在那时确定。提交者在暂停权限后还可以在 30 天后请求复审，并且每 30 天复审一次（除非暂停期少于 30 天）。完全撤销权限的提交者可以在 6 个月后请求复审。该复审政策是 严格非正式的，在所有情况下，核心小组保留在认为原决策正确时可以选择是否审理复审请求的权利。

在项目运营的其他方面，核心小组是提交者的一个子集，必须遵守 相同的规则。仅仅因为某人是核心成员，并不意味着他们可以越过任何已定的规则；核心小组的“特别权力”仅在作为小组行动时才生效，而非个人行为。作为个体，核心团队成员首先是提交者，其次才是核心成员。

20.1. 细节

1. 尊重其他提交者。 这意味着你需要将其他提交者视为同行开发者。尽管我们偶尔会试图证明相反的事情，但成为提交者并不是因为愚蠢，而最让人不爽的事情就是被同行如此对待。无论我们是否总是感到彼此尊重（每个人都有情绪低落的时候），我们仍然必须始终以尊重的态度对待其他提交者，无论是在公开论坛上还是在私人邮件中。

   长期合作的能力是这个项目最宝贵的资产，它远比任何代码更重要，将关于代码的争论转化为影响我们长期和谐合作的问题，是无法接受的。

   为了遵守这一规则，当你生气时，不要发送电子邮件，或者以可能让他人感到不必要对抗的方式行事。先冷静下来，然后思考如何以最有效的方式沟通，来让对方相信你的论点是正确的，而不是为了短期内的宣泄而进行一场长期的争论。这不仅是非常不好的“能量经济学”，反复在公众场合表现出攻击性行为会严重影响我们合作的能力，项目领导层会严肃处理，并可能导致提交权限的暂停或终止。项目领导层会考虑到公开和私下的沟通，但不会主动披露私人沟通，除非相关提交者自愿提供。

   这些都不是项目领导层希望看到的，但团结至上。没有任何代码或好建议值得为此做出妥协。

2. 尊重其他贡献者。 你曾不是提交者。曾几何时，你也是位贡献者。请始终记住这一点。记住曾经尝试寻求帮助和关注的感受。不要忘记你作为贡献者时的感受。记住那个时候，自己是多么重要。不要打击、贬低或轻视贡献者。尊重他们。他们是我们未来的提交者。与提交者一样，他们对项目的贡献同样重要。毕竟，在成为提交者之前，你也是如此贡献过。切记这一点。
3. 在提交任何重大更改之前进行讨论。 仓库不是初次提交更改的地方，那里是用来纠正错误或者争论的，通常是在邮件列表或通过使用 Phabricator 服务时进行。提交只有在达成一定共识后才会发生。这并不意味着在纠正每个明显的语法错误或手册页拼写错误之前都需要得到许可，只是要培养一种感觉，当提议的更改不是那么显而易见时，最好先征求一些反馈。在一般情况下，如果某个变更明显比之前的版本更好，人们不介意大规模的更改，但他们不喜欢被 突然 改变。确保事情走上正轨的最佳方式是让一个或多个提交者进行代码审查。

   如果不确定，请请求审查！

5. 任何有争议的更改必须在维护者要求时撤回，直到争议解决。如果涉及安全相关的更改，则可以在安全官员的裁量下覆盖维护者的意愿。 在冲突时（每一方都坚信自己是对的），这可能很难接受，但版本控制系统让我们不必让争论继续下去，直接撤回有争议的更改，冷静下来后再找出最佳的解决方案。如果更改最终被证明是正确的，完全可以轻松地恢复。如果结果证明这不是最好的选择，那么用户就不必在争论期间忍受无效的更改。很少会有人在仓库中要求撤回更改，因为大多数争议都在提交前通过讨论解决，但在这种罕见的情况下，撤回更改应毫不犹豫，以便我们立即着手解决它是否合理的问题。

6. 更改应提交到 FreeBSD-CURRENT 而不是 FreeBSD-STABLE，除非发布工程师特别许可，或除非更改与 FreeBSD-CURRENT 无关。任何重要或非紧急的更改也应在 FreeBSD-CURRENT 中放置至少3天，确保充分的测试。发布工程师对 FreeBSD-STABLE 分支拥有与规则5相同的权威。 这是一个“不要争论”的问题，因为最终如果更改导致问题，责任由发布工程师承担。请尊重这一点，并在涉及 FreeBSD-STABLE 分支时全力配合发布工程师。FreeBSD-STABLE 的管理可能对外人来说显得过于保守，但要记住保守主义是 FreeBSD-STABLE 的标志，不同规则适用于 FreeBSD-STABLE 分支，不能立即将更改合并到 FreeBSD-STABLE。FreeBSD-CURRENT 开发者需要一定的时间进行测试，因此请允许时间过去，除非该更改对 FreeBSD-STABLE 至关重要、时间敏感或明显到不需要更多测试（例如拼写修正、显而易见的bug或拼写错误修复等）。换句话说，运用常识。

   对于安全分支（例如 releng/9.3）的更改，必须经过 Security Officer Team 成员或在某些情况下，Release Engineering Team 成员的批准。

7. 不要在公开场合与其他提交者争斗；这看起来很不好。 FreeBSD 项目有公共形象，必须维护好这个形象，这对我们所有人都很重要，特别是在我们吸引新成员时。即便大家都极力控制情绪，也难免会发生情绪失控、言辞激烈的情况。最好的做法是在此类情况发生时尽量减少影响，直到大家冷静下来为止。不要在公开场合发泄愤怒的言辞，也不要将私人通信或其他私人交流转发到公开邮件列表、邮件别名、即时通讯渠道或社交媒体网站上。一个人在私下发送的言辞通常比在公开场合更直白、尖锐，这些内容不适合公开场合——它们只会加剧已经不好的局势。如果发送者至少有尊重，不将其公之于众，那么你也应当同样尊重这一点，保持私密。如果你觉得自己受到其他开发者的不公对待，导致痛苦，请将此事报告给核心小组，而不是公开化。核心小组会尽力充当和平使者，恢复理性。如果争论涉及对代码库的更改，且参与者未能达成和解，核心小组可能会指定一个双方同意的第三方来解决争端。所有相关方必须同意接受该第三方的决定。

8. 尊重所有代码冻结并及时阅读 committers 和 developers 邮件列表，以便了解代码冻结的生效时间。 在代码冻结期间提交未经批准的更改是一个非常大的错误，提交者需要保持最新的状态，了解发生的事情，避免在长时间缺席后跳进来并提交积累的 10 兆字节的内容。那些经常滥用此行为的人，将被暂停提交权限，直到他们从我们在格林兰岛举办的 FreeBSD 快乐再教育营返回。

9. 对于任何程序不确定时，先询问！ 许多错误都是因为某人在匆忙中假设自己知道正确的做法。如果你以前没有做过，通常你并不知道我们是如何操作的，真的需要先问一问，否则你会在公开场合完全让自己出丑。问“我到底该怎么做？”没有什么可耻的。我们已经知道你是个聪明人，否则你不会成为提交者。

11. 未经相应维护者 明确 批准，不要提交第三方软件。 第三方软件是指所有位于 src/contrib、src/crypto 或 src/sys/contrib 目录下的软件。

上述目录用于通常从供应商分支导入的第三方软件。将内容提交到这些目录可能会在导入新版本的软件时带来不必要的麻烦。一般来说，考虑将补丁发送到上游供应商。补丁可以在维护者许可下先提交到 FreeBSD。

修改上游软件的原因包括希望对紧密耦合的依赖关系进行严格控制，或是上游代码的可移植性问题。无论原因如何，尽量减少复刻的维护负担对其他维护者是有益的。避免提交琐碎或外观上的更改，因为这些会使之后的合并变得更加困难：这些补丁需要在每次导入时手动重新验证。

20.2. 多架构政策

FreeBSD 在最近的发布周期中新增了多个架构 Port，真正不再是一个以 i386™ 为中心的操作系统。为了使 FreeBSD 在我们支持的平台上保持良好的可移植性，核心团队制定了以下规定：

我们的 32 位参考平台是 i386，64 位参考平台是 amd64。重大设计工作（包括重大 API 和 ABI 更改）必须在至少一个 32 位平台和一个 64 位平台上证明其可行性，最好是在主要参考平台上，才能提交到源码树中。

开发者还应了解我们的架构长期支持的 Tier 政策。这里的规则是为了在开发过程中提供指导，并且与发布时列出的特性和架构的要求不同。在开发过程中，架构的支持规则比发布时的规则要宽松得多。

20.3. 多编译器政策

FreeBSD 使用 Clang 和 GCC 进行构建。该项目以一种谨慎且可控的方式进行，以最大化这种额外工作的好处，同时将额外工作的量降到最低。支持 Clang 和 GCC 提高了我们用户的灵活性。这些编译器有不同的优缺点，支持这两者让用户可以根据自己的需求选择最佳的编译器。Clang 和 GCC 支持类似的 C 和 C++ 方言，只需相对较少的条件代码。该项目通过使用两种编译器的特性，增加了代码覆盖率并提高了代码质量。通过支持这种范围，项目能够在更多用户环境中构建并利用更多 CI 环境，从而提高了用户的便利性，并为他们提供了更多测试工具。通过严格限制支持的版本范围为这些编译器的现代版本，项目避免了过度增加测试矩阵。旧的和冷门的编译器以及旧的语言方言有极其有限的支持，允许用户程序使用它们进行构建，但不要求基本系统必须使用这些编译器进行构建。具体的平衡仍在不断演变，以确保额外工作的好处大于它所带来的负担。该项目曾经支持非常旧的 Intel 编译器或旧版本的 GCC，但我们用精心选择的现代编译器替代了对这些过时编译器的支持。本节记录了我们在哪里使用不同的编译器，以及对此的期望。

FreeBSD 项目提供了一个内嵌的 Clang 编译器。由于它在源码树中，因此这是最受支持的编译器。所有更改在提交之前必须与它编译通过。根据更改的性质，应使用此编译器进行完整的测试。

FreeBSD 项目还在 GitHub 上拥有一些 CI 管道。对于 GitHub 上的拉取请求和推送到 GitHub 分支的某些代码，运行了一些交叉编译作业。这些作业测试 FreeBSD 使用一个可能比内嵌编译器版本落后一个大版本的 Clang 版本进行构建。

FreeBSD 项目还在升级编译器。Clang 和 GCC 都是快速发展的目标。一些更改可能会在编译器到达之前先在源码树中实施，例如移除旧式的 K&R 函数声明和定义。提交者应尽量注意这一点，并乐于调查新编译器可能带来的代码问题或更改。此外，在新的编译器版本加入源码树后，若怀疑存在未被检测的回归，可能需要使用旧版本进行编译。

除了编译器，LLVM 的 LLD 和 GNU 的 binutils 也由编译器间接使用。提交者应注意汇编语法和链接器特性的差异，并确保两者的变种都能正常工作。这些组件将作为 FreeBSD CI 任务的一部分进行测试，适用于 Clang 或 GCC。

FreeBSD 项目提供了头文件和库，允许使用其他编译器来构建非基本系统中的软件。这些头文件支持将环境尽可能严格地与标准一致，支持 ANSI-C 先前方言，直到 C89，并处理我们庞大的 Ports 中所发现的其他边缘情况。这个支持限制了旧标准在头文件中的淘汰，但不限制基本系统更新到更新的方言，也不要求基本系统整体上使用这些旧标准进行编译。破坏这一支持将导致 Ports 中的软件包构建失败，因此应尽量避免，并在容易修复时尽快修复。

FreeBSD 构建系统目前适应这些不同的环境。随着编译器中新警告的加入，项目尝试修复它们。然而，有时这些警告需要大量重构，因此会通过使用根据编译器版本评估的 make 变量某种方式被抑制。开发者应注意这一点，确保任何特定于编译器的标志都能正确地进行条件处理。

20.3.1. 当前编译器版本

目前，内嵌的编译器是 Clang 15.x。目前，GCC 12 和 Clang 12、13、14、15 在 GitHub 和项目的 CI Jenkins 任务中进行了测试。相关工作正在进行，以准备将 Clang 16 版本加入源码树。最旧的项目支持分支使用 Clang 12，因此构建的引导部分必须适用于 Clang 12 至 15 的主版本。

20.4. 其他建议

不要将样式修复与新功能混合。样式修复是指不修改代码功能的任何更改。混合这些更改会在询问修订差异时混淆功能性更改，这可能会隐藏任何新引入的 bug。不要在提交 doc/ 时将空白更改与内容更改混合。差异中的额外杂乱会使翻译人员的工作更加困难。相反，请将任何样式或空白更改放在单独的提交中，并在提交消息中明确标明这些更改。

20.5. 弃用功能

当需要从基本系统中删除功能时，请尽可能遵循以下指南：

1. 在手册页和可能的发布说明中提到该选项、工具或接口已弃用。使用弃用的功能会生成警告。

2. 该选项、工具或接口在下一个主要（零点版本）发布之前保留。

3. 该选项、工具或接口被移除且不再文档化。它现在已过时。通常，最好在发布说明中指出其移除。

20.6. 隐私与保密

1. 大多数 FreeBSD 的事务是公开的。 FreeBSD 是一项 开源 项目。这意味着不仅任何人都可以使用源代码，而且大多数开发过程都向公众开放，接受公众审查。

2. 某些敏感事项必须保持私密或处于禁运状态。 不幸的是，无法实现完全透明。作为 FreeBSD 开发者，你将拥有一定程度的特权信息访问权限。因此，你需要遵守某些保密要求。有时保密的需求来自外部合作者或具有特定时间限制的要求。大多数情况下，这是关于不公开私人通信的。

3. 安全官员单独控制安全公告的发布。 当有影响多个操作系统的安全问题时，FreeBSD 经常依赖提前获取信息，以便为协调发布准备安全公告。除非可以信任 FreeBSD 开发者维护安全性，否则不会提前提供此类信息。安全官员负责控制漏洞信息的预发布访问，并决定所有公告的发布时机。如果有相关知识的开发者能够在保密条件下提供帮助，安全官员可以请求协助准备安全修复。

4. 与核心小组的通信应保密，直到必要时。 向核心小组的通信最初将被视为保密。然而，核心小组的大多数事务最终会被总结在每月或每季度的核心报告中。但会小心避免公开任何敏感细节。某些特别敏感的议题可能完全不会报告，并且只会保留在核心小组的私人档案中。

5. 对于访问某些商业敏感数据，可能需要签署保密协议。 访问某些商业敏感数据可能仅在签署保密协议的情况下才可获得。FreeBSD 基金会的法律人员必须在任何具有约束力的协议签署之前进行咨询。

6. 未经许可不得公开私人通信。 除了上述特定要求外，一般期望未经所有相关方的同意，不得公开开发者之间的私人通信。在将消息转发到公共邮件列表或发布到可能被原始通信者之外的其他人访问的论坛或网站之前，请先征得许可。

7. 项目专用或受限访问渠道的通信必须保持私密。 类似于个人通信，某些内部通信渠道（包括 FreeBSD 提交者专用邮件列表和受限访问的 IRC 渠道）被视为私人通信。发布这些来源的材料需要获得许可。

8. 核心小组可以批准公开。 如果由于通信者数量过多或因不合理地拒绝发布而难以获得许可，核心小组可以批准发布这些私密事务，前提是这些事务值得更广泛的公开。

21. 支持多种架构

FreeBSD 是一个高度可移植的操作系统，旨在支持多种不同类型的硬件架构。保持机器相关（MD）代码与机器无关（MI）代码的清晰分离，并尽量减少 MD 代码，是我们保持对当前硬件趋势灵活性的战略重要组成部分。每增加一种硬件架构的支持，都会显著增加代码维护、工具链支持和发布工程的成本。它还会大幅提高对内核更改进行有效测试的成本。因此，强烈的动机是区分各种架构支持的不同级别，同时在一些被视为 FreeBSD “目标受众”的关键架构上保持强大的支持。

21.1. 一般意图声明

FreeBSD 项目专注于“生产质量的商业现货（COTS）工作站、服务器和高端嵌入式系统”。通过将重点保持在这些环境中感兴趣的有限架构集上，FreeBSD 项目能够维持高水平的质量、稳定性和性能，同时最小化项目中各个支持团队的负担，如 Port 团队、文档团队、安全官员和发布工程团队。硬件支持的多样性通过提供新特性和使用机会，拓宽了 FreeBSD 用户的选择，但这些好处必须始终仔细考虑与额外平台支持相关的实际维护成本。

FreeBSD 项目将平台目标分为四个级别。每个级别包括消费者可以依赖的保证清单，以及项目和开发者为履行这些保证所承担的义务。这些清单定义了每个级别的最低保证。项目和开发者可能提供超出最低保证的额外支持，但这些额外支持不作保证。每个平台目标会根据每个稳定分支分配到一个特定的级别。因此，某个平台目标可能会在并行的稳定分支中分配到不同的级别。

21.2. 平台目标

硬件平台的支持由两个组件组成：内核支持和用户空间应用程序二进制接口（ABI）。内核平台支持包括使 FreeBSD 内核能够在硬件平台上运行所需的内容，如机器相关的虚拟内存管理和设备驱动程序。用户空间 ABI 指定了用户进程与 FreeBSD 内核和基本系统库进行交互的接口。用户空间 ABI 包括系统调用接口、公共数据结构的布局和语义、以及传递给子程序的参数的布局和语义。某些 ABI 组件可能由规范定义，如 C++ 异常对象的布局或 C 函数的调用约定。

FreeBSD 内核也使用 ABI（有时称为内核二进制接口（KBI）），包括公共数据结构的语义和布局，以及内核中公共函数的参数的语义和布局。

FreeBSD 内核可以支持多个用户空间 ABI。例如，FreeBSD 的 amd64 内核支持 FreeBSD amd64 和 i386 用户空间 ABI，以及 Linux x86_64 和 i386 用户空间 ABI。FreeBSD 内核应支持一个“本地” ABI 作为默认 ABI。本地 ABI 通常与内核 ABI 共享某些特性，如 C 调用约定、基本类型的大小等。

内核和用户空间 ABI 都有相应的级别定义。在常见的情况下，平台的内核和 FreeBSD ABI 被分配到相同的级别。

21.2.1. 第一层：完全支持的架构

第一层平台是最成熟的 FreeBSD 平台。它们由安全官员、发布工程和 Ports 管理团队支持。第一层架构预计在 FreeBSD 操作系统的所有方面（包括安装和开发环境）都具有生产质量。

FreeBSD 项目为第一层平台的消费者提供以下保证：

• 发布工程团队将提供官方的 FreeBSD 发布镜像。

• 将为受支持的版本提供安全通告和勘误通知的二进制更新和源代码补丁。

• 将为受支持的分支提供安全通告的源代码补丁。

• 跨平台的安全通告的二进制更新和源代码补丁通常会在公告时提供。

• 用户空间 ABI 的变化通常会包含兼容性补丁，以确保在该平台为第一层的任何稳定分支上编译的二进制文件正确运行。这些补丁可能不会在默认安装中启用。如果对 ABI 更改没有提供兼容性补丁，缺少补丁的情况将会在发布说明中清楚地记录。

• 某些内核 ABI 部分的变化将包括兼容性补丁，以确保在该分支上最早支持的版本中编译的内核模块正确运行。请注意，并非所有内核 ABI 部分都受到保护。

• 第三方软件的官方二进制包将由 Port 团队提供。对于嵌入式架构，这些包可能会从不同架构交叉构建。

• 大多数相关的 Port 应该能够构建，或者具有适当的过滤器，防止不适当的 Port 被构建。

• 不特定于平台的新功能将在所有第一层架构上完全功能。

• 用于与较旧稳定分支编译的二进制文件的功能和兼容性补丁可能会在较新的主版本中删除。这些删除将会在发布说明中清楚地记录。

• 第一层平台应该有完整的文档。基本操作将在 FreeBSD 手册中记录。

• 第一层平台将包含在源代码树中。

• 第一层平台应该能够自我托管，无论是通过内建工具链还是外部工具链。如果需要外部工具链，将提供外部工具链的官方二进制包。

为了保持第一层平台的成熟，FreeBSD 项目将维护以下资源来支持开发：

• 在 FreeBSD.org 集群或其他易于所有开发者访问的位置提供构建和测试自动化支持。嵌入式平台可能使用 FreeBSD.org 集群中的仿真器代替实际硬件。

• 包含在 make universe 和 make tinderbox 目标中。

• 在 FreeBSD 集群中为包构建提供专用硬件（无论是本地构建还是通过 qemu-user）。

为了维持第一层平台的状态，开发者需要提供以下内容：

• 对源代码树的更改不得故意破坏第一层平台的构建。

• 第一层架构必须拥有成熟、健康的用户生态系统和活跃的开发者。

• 开发者应该能够在常见的非嵌入式第一层系统上构建包。这可以意味着，如果平台在该平台上常见，使用本地构建，或者可以意味着在其他第一层架构上进行交叉构建。

• 更改不能破坏用户空间 ABI。如果需要更改 ABI，应通过符号版本控制或共享库版本提升提供对现有二进制文件的 ABI 兼容性。

• 合并到 Stable 分支的更改不能破坏内核 ABI 的受保护部分。如果需要更改内核 ABI，应对更改进行修改，以保持现有内核模块的功能。

21.2.2. 第二层：开发性和小众架构

第二层平台是功能性存在，但成熟度较低的 FreeBSD 平台。它们不受安全官员、发布工程和 Ports 管理团队的支持。

第二层平台可能是仍在积极开发中的第一层平台候选者。达到生命周期终结的架构也可能从第一层状态转为第二层状态，因为持续保持系统在生产质量状态下的资源可用性减少。受到良好支持的小众架构也可以是第二层。

FreeBSD 项目为第二层平台的消费者提供以下保证：

• Port 基础设施应包括对第二层架构的基本支持，足以支持构建 Port 和包。这包括对基本包（如 ports-mgmt/pkg）的支持，但不能保证所有 Port 都能够构建或正常运行。

• 不特定于平台的新功能，如果未实现，应该在所有第二层架构上可行。

• 第二层平台将包含在源代码树中。

• 第二层平台应该能够自我托管，无论是通过内建工具链还是外部工具链。如果需要外部工具链，将提供外部工具链的官方二进制包。

• 第二层平台应提供功能性内核和用户空间，即使未提供官方发布的分发版。

为了保持第二层平台的成熟，FreeBSD 项目将维护以下资源来支持开发：

• 包含在 make universe 和 make tinderbox 目标中。

为了维持第二层平台的状态，开发者需要提供以下内容：

• 对源代码树的更改不得故意破坏第二层平台的构建。

• 第二层架构必须拥有活跃的用户和开发者生态系统。

• 虽然允许更改破坏用户空间 ABI，但不应无故破坏 ABI。重大用户空间 ABI 更改应限制在主版本中。

• 尚未在第二层架构上实现的新功能，应提供在这些架构上禁用它们的方式。

21.2.3. 第三层：实验性架构

第三层平台至少有部分 FreeBSD 支持。它们不受安全官员、发布工程和 Ports 管理团队的支持。

第三层平台是处于开发初期的架构，面向非主流硬件平台，或者是被认为不太可能在未来广泛使用的遗留系统。第三层平台的初步支持可能存在于一个独立的仓库中，而非主源代码仓库。

FreeBSD 项目不为第三层平台的消费者提供任何保证，也不承诺维护支持开发的资源。第三层平台可能并不总是可构建的，内核或用户空间 ABI 也不被视为稳定的。

21.2.4. 不支持的架构

其他平台在任何形式上都不受项目支持。项目以前将这些平台称为第四层系统。

平台转为不受支持后，所有对该平台的支持将从源代码、Ports 和文档树中移除。请注意，Ports 支持应在平台仍受 Ports 支持的分支中保持。

21.3. 改变架构层级的政策

系统只能在获得 FreeBSD 核心团队批准后，才能从一个层级移动到另一个层级。核心团队将与安全官员、发布工程和 Ports 管理团队合作做出这一决定。要将平台晋升到更高的层级，必须在晋升完成之前满足任何缺失的支持保证。

22. Port 相关常见问题

22.1. 添加新 Port

22.1.1. 如何添加新 Port ？

SUBDIR += newport

Port 及其类别的 Makefile 准备好后，可以提交新 Port ：

% git add category/Makefile category/newport
% git commit
% git push

22.1.2. 添加新 Port 时需要注意的其他事项？

检查 Port，最好确保它能够正确编译和打包。

你不必消除所有警告，但请确保修复简单的警告。

如果 Port 是通过 PR 提交的，请关闭 PR。关闭 PR 时，状态改为 Issue Resolved，并将解决方案设为 Fixed。

注意

复制

# make package
# make deinstall
# pkg add 上述构建的包
# make deinstall
# make reinstall
# make package`

请注意，poudriere 是包构建的参考工具，如果无法在 poudriere 中构建 Port，Port 将被移除。

22.2. 移除现有 Port

22.2.1. 如何移除现有 Port？

首先，请阅读关于仓库副本的章节。在移除 Port 之前，你需要验证是否没有其他 Port 依赖于它。

• 确保该 Port 在 Ports 中没有依赖：

  • 该 Port 的 PKGNAME 在最近的 INDEX 文件中只出现一次。

  • 没有其他 Port 在其 Makefile 中包含该 Port 的目录或 PKGNAME。

    技巧

• 然后，移除 Port：

  • 使用 git rm 移除该 Port 的文件和目录。

  • 从父目录的 Makefile 中移除该 Port 的 SUBDIR 列表。

  • 在 ports/MOVED 中添加条目。

  • 如果该 Port 在 ports/LEGAL 中，移除该 Port。

22.3. 如何将 Port 移到新位置？

2. 从旧类别的 Makefile 中移除 SUBDIR 条目，并将 SUBDIR 条目添加到新类别的 Makefile 中。

3. 在 ports/MOVED 中添加条目。

4. 在 ports/security/vuxml 中搜索 xml 文件中的条目，并相应地调整它们。特别是，检查以前的包是否有可能包含新 Port 的版本。

5. 使用 git mv 移动 Port。

6. 提交更改。