# 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 Fork 原仓库的主分支（main），保持主分支不变，然后创建一个新的分支 B，用于开发和修改。

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

```sh
git pull   # 在当前分支上拉取远程更新
git checkout B   # 切换到分支 B
git diff -U999999 origin/main > 2023-1-24.diff   # 在分支 B 下生成与远程 main 分支的差异，并保存到 2023-1-24.diff 文件
```

## 完整的 git 提交操作示例

```sh
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 文件，将其上传至 [此链接](https://reviews.freebsd.org/differential/)（页面右上角有 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 代理：

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

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

```sh
$ git branch -a
```

* 切换到本地分支 A：

```sh
$ 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 安装：

```sh
# pkg install groff ghostscript10
```

* 或者使用 Ports 安装：

```sh
# 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$` 来解决此问题。
* 正文的组织和排序不够合理，并未按功能模块或其他逻辑编排，因此不适用于系统学习，但可用于快速查阅。

## 课后习题

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/fu-lu-i-gong-ju-yu-zi-yuan/freebsd-kai-fa-can-yu-zhi-nan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.