FreeBSD 开发参与指南

方法概述

参与 FreeBSD 开发有多种方式，包括翻译文档、提交 Port、提交 Bug 报告。

需要阅读 FreeBSD 项目代码评审与协作开发平台说明文档：https://wiki.freebsd.org/Phabricator。

相关文档已有详细说明，需先注册账号，并可关联 GitHub。但关联后用户名的显示格式可能与预期存在差异。

除 Phabricator 外，FreeBSD 目前也接受通过 GitHub Pull Request 提交修改。对于较为简单直接的改动，GitHub PR 是目前推荐的提交方式。具体要求包括：改动应基本可提交（committer 只需少于 10 分钟的额外工作即可合并）、通过 GitHub CI 检查、可及时回应反馈、涉及文件不超过约 10 个且改动不超过约 200 行。同一修改应只通过一种方式提交，避免同时创建 Phabricator 评审和 GitHub PR。

对于代码问题，一种较简单的解决方案是通过 GitHub 复刻原仓库的主分支（main），保持主分支不变，然后创建一个新的分支 B，用于开发和修改。

在完成修改或开发后，将 main 分支和 B 分支同步到最新状态（可通过网页端同步），然后在分支 B 上执行以下命令：

git pull   # 在当前分支上拉取远程更新
git checkout B   # 切换到分支 B
git diff -U999999 origin/main > 2023-1-24.diff   # 生成当前分支与远程 main 分支的差异，输出至 2023-1-24.diff

完整的 git 提交操作示例

root@generic:~ # git clone https://github.com/freebsd/freebsd-ports # 克隆 freebsd-ports 仓库到本地
Cloning into 'freebsd-ports'...
remote: Enumerating objects: 6264931, done.
remote: Counting objects: 100% (15563/15563), done.
remote: Compressing objects: 100% (9249/9249), done.
remote: Total 6264931 (delta 6507), reused 14986 (delta 6260), pack-reused 6249368 (from 1)
Receiving objects: 100% (6264931/6264931), 2.12 GiB | 10.73 MiB/s, done.
Resolving deltas: 100% (3615966/3615966), done.
Checking objects: 100% (16777216/16777216), done.
Updating files: 100% (161546/161546), done.
root@generic:~ # cd freebsd-ports/
root@generic:~/freebsd-ports # git branch -a # 查看分支
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/rpi-firmware
root@generic:~/freebsd-ports # git checkout rpi-firmware # 切换到 rpi-firmware 分支（通过 GitHub 网页创建）
branch 'rpi-firmware' set up to track 'origin/rpi-firmware'.
Switched to a new branch 'rpi-firmware'
root@generic:~/freebsd-ports # git diff -U999999 origin/main > 2024.diff # 生成与远程 main 分支的差异，输出至 2024.diff
root@generic:~/freebsd-ports # ls -l 2024.diff
-rw-r--r--  1 root wheel 18021 Oct  6 03:59 2024.diff

上述操作将在分支 B 的根目录下生成 .diff 文件，将其上传至此链接（页面右上角有 Create 入口），点击 Create 并填写相关信息，即可提交审阅。

这是一种相对简便的提交方式。每次提交的修改量不应过大。

提交完成后，在 https://bugs.freebsd.org/bugzilla 新建一个 Bug，说明修改内容，并附上 https://reviews.freebsd.org 的链接。完成后，再在 https://reviews.freebsd.org 中附上该 Bug 页面链接，否则可能长时间无人处理。

技巧
diff 文件不视作修改产生的文件，下次生成 diff 时无需提前删除上一次的 diff 文件。

上述操作适用于 FreeBSD 文档源（doc、src）和 Ports。此外，还有少部分操作需要在 GitHub 上完成，例如状态报告。

技巧
FreeBSD 源代码的修改参与方式较为灵活，任何人都可以通过代码评审系统提交修改。Linux 内核开发则主要通过内核维护邮件列表，提交的补丁需要经过维护者的审核和接纳。

附录：一些可能用得到的命令

配置全局 Git HTTP 代理：

$ git config --global http.proxy http://192.168.1.169:7890

技巧
上述示例中的 192.168.1.169、7890 为占位符，须替换为实际的值。

列出本地和远程的所有分支：

$ git branch -a

切换到本地分支 A：

$ git checkout A

如何开发 Port

建议阅读《FreeBSD Port 开发者手册》。

FreeBSD 的软件以 Port 形式提供，开发者无需考虑如何打包为二进制软件包等问题。Port 本身也不包含软件源代码，类似于 Gentoo（Gentoo Portage 的设计理念源自 FreeBSD Ports），因此理论上移植难度较低。

完成移植后，可向 Bug 报告系统提交请求合并的报告（也可直接发送到 https://reviews.freebsd.org/），具体格式可以参考列表中其他软件的示例。如果长时间无人回应，可向邮件列表发送询问，确认是否有人能够协助提交。如果仍无人回应，可在一周后再次发送。

参考文献

FreeBSD Project. FreeBSD Jenkins[EB/OL]. [2026-03-26]. https://ci.freebsd.org/. 提供 FreeBSD 持续集成构建与测试状态的实时监控。
FreeBSD Project. FreeBSD pkg 二进制软件包构建状态网页[EB/OL]. [2026-03-26]. https://pkg-status.freebsd.org/. 提供了 Ports 包构建状态与失败分析的可视化界面。
FreeBSD Project. Contribution Guidelines for GitHub[EB/OL]. [2026-04-17]. https://github.com/freebsd/freebsd-src/blob/main/CONTRIBUTING.md. FreeBSD 源代码贡献指南，说明了 GitHub PR 与 Phabricator 两种提交方式的适用场景。
The FreeBSD Foundation. Submitting GitHub Pull Requests to FreeBSD[EB/OL]. [2026-04-17]. https://freebsdfoundation.org/submitting-github-pull-requests-to-freebsd/. 介绍如何通过 GitHub 向 FreeBSD 提交 Pull Request 的完整流程。

利用脚本自动生成 BSD libc 库文本

首先，安装所需的软件包。

使用 pkg 安装：

# pkg install groff ghostscript10

或者使用 Ports 安装：

# cd /usr/ports/textproc/groff/ && make install clean
# cd /usr/ports/print/ghostscript10/ && make install clean

运行脚本即可在同路径文件夹下找到 PDF 文档。脚本和现成的文档参见：FreeBSD-Ask. BSDlibc[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/BSDlibc.

参考文献

mrclksr. where's bsd libc documentation?[EB/OL]. [2026-03-26]. https://web.archive.org/web/20180216154558/https://forums.freebsd.org/threads/wheres-bsd-libc-documentation.63107/. 探讨 BSD libc 文档生成方法。原方案已失效。

对原方案的改进：

if zgrep -q '.Lb libc' $i && zgrep -q '.Sh LIBRARY' $i; then 这一句的问题在于 .Lb libc 不仅匹配 libc，还会匹配 libcalendar 等以 libc 开头的库。可以改写为 .Lb libc$ 来解决此问题。
正文的组织和排序不够合理，并未按功能模块或其他逻辑编排，因此不适用于系统学习，但可用于快速查阅。

课后习题

复刻 FreeBSD 源代码仓库，修复文档中的一个小问题，生成 diff 文件并提交代码审阅流程。
分析 FreeBSD 与 Linux 内核贡献机制的差异，探讨其对社区参与门槛的影响。
改进 BSD libc 文档生成脚本，按功能模块重新组织文档结构并生成新的 PDF 文档。

上一页FreeBSD 邮件列表订阅下一页microSD 卡参数简介

最后更新于 2天前