Contributing to FreeBSD Development

Method Overview

There are multiple ways to participate in FreeBSD development, including translating documentation, submitting Ports, and submitting bug reports.

You need to read the FreeBSD project code review and collaborative development platform documentation: https://wiki.freebsd.org/Phabricator.

The relevant documentation has detailed instructions; you need to register an account first, and you can link it to GitHub. However, after linking, the username display format may differ from expectations.

In addition to Phabricator, FreeBSD currently also accepts modifications submitted via GitHub Pull Requests. For relatively simple and straightforward changes, GitHub PR is the currently recommended submission method. Specific requirements include: changes should be essentially commit-ready (a committer should need less than 10 minutes of additional work to merge), pass GitHub CI checks, respond to feedback promptly, involve no more than approximately 10 files and no more than approximately 200 lines of changes. The same modification should only be submitted through one method; avoid creating both a Phabricator review and a GitHub PR simultaneously.

For code issues, a relatively simple solution is to fork the main branch of the original repository on GitHub, keep the main branch unchanged, and then create a new branch B for development and modifications.

After completing the modifications or development, sync the main branch and branch B to the latest state (you can sync via the web interface), then run the following commands on branch B:

git pull   # Pull remote updates on the current branch
git checkout B   # Switch to branch B
git diff -U999999 origin/main > 2023-1-24.diff   # Generate the diff between the current branch and the remote main branch, output to 2023-1-24.diff

Complete git Commit Example

root@generic:~ # git clone https://github.com/freebsd/freebsd-ports # Clone the freebsd-ports repository locally
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 # View branches
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/rpi-firmware
root@generic:~/freebsd-ports # git checkout rpi-firmware # Switch to the rpi-firmware branch (created via GitHub web interface)
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 # Generate the diff with the remote main branch, output to 2024.diff
root@generic:~/freebsd-ports # ls -l 2024.diff
-rw-r--r--  1 root wheel 18021 Oct  6 03:59 2024.diff

The above operations will generate a .diff file in the root directory of branch B. Upload it to this link (there is a Create entry in the upper right corner of the page), click Create and fill in the relevant information to submit for review.

This is a relatively simple submission method. The amount of changes in each submission should not be too large.

After submission, create a new bug at https://bugs.freebsd.org/bugzilla, describe the modification, and attach the link to https://reviews.freebsd.org. After that, attach the bug page link in https://reviews.freebsd.org; otherwise, it may go unaddressed for a long time.

Tip

diff files are not considered files generated by modifications; there is no need to delete the previous diff file before generating a new one.

The above operations apply to FreeBSD documentation sources (doc, src) and Ports. Additionally, a small number of operations need to be completed on GitHub, such as status reports.

Tip

The participation method for FreeBSD source code modifications is relatively flexible; anyone can submit changes through the code review system. Linux kernel development, on the other hand, primarily uses kernel maintainer mailing lists, where submitted patches need to be reviewed and accepted by maintainers.

Appendix: Some Potentially Useful Commands

• Configure a global Git HTTP proxy:

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

Tip

In the above example, 192.168.1.169 and 7890 are placeholders and must be replaced with actual values.

• List all local and remote branches:

$ git branch -a

• Switch to local branch A:

$ git checkout A

How to Develop a Port

It is recommended to read the FreeBSD Porter's Handbook.

FreeBSD software is provided in the form of Ports; developers do not need to consider how to package it as binary packages. A Port itself does not contain the software source code, similar to Gentoo (Gentoo Portage's design philosophy originated from FreeBSD Ports), so the theoretical difficulty of porting is relatively low.

After completing the port, you can submit a merge request to the bug reporting system (or directly to https://reviews.freebsd.org/); for the specific format, you can refer to examples of other software in the list. If there is no response for a long time, you can send an inquiry to the mailing list to confirm whether anyone can assist with the submission. If there is still no response, you can send another inquiry after one week.

References

• FreeBSD Project. FreeBSD Jenkins[EB/OL]. [2026-03-26]. https://ci.freebsd.org/. Provides real-time monitoring of FreeBSD continuous integration builds and test status.
• FreeBSD Project. FreeBSD pkg Binary Package Build Status Page[EB/OL]. [2026-03-26]. https://pkg-status.freebsd.org/. Provides a visualization interface for Ports package build status and failure analysis.
• FreeBSD Project. Contribution Guidelines for GitHub[EB/OL]. [2026-04-17]. https://github.com/freebsd/freebsd-src/blob/main/CONTRIBUTING.md. FreeBSD source code contribution guidelines, explaining the applicable scenarios for GitHub PR and Phabricator submission methods.
• The FreeBSD Foundation. Submitting GitHub Pull Requests to FreeBSD[EB/OL]. [2026-04-17]. https://freebsdfoundation.org/submitting-github-pull-requests-to-freebsd/. Introduces the complete process of submitting Pull Requests to FreeBSD via GitHub.

Generating BSD libc Library Documentation Using a Script

First, install the required packages.

• Install using pkg:

# pkg install groff ghostscript10

• Or install using Ports:

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

Run the script and you will find the PDF document in the same directory. For the script and ready-made documentation, see: FreeBSD-Ask. BSDlibc[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/BSDlibc.

References

• 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/. Discusses methods for generating BSD libc documentation. The original approach is no longer functional.

Improvements to the original approach:

• The issue with if zgrep -q '.Lb libc' $i && zgrep -q '.Sh LIBRARY' $i; then is that .Lb libc matches not only libc but also libraries starting with libc, such as libcalendar. This can be resolved by rewriting it as .Lb libc$.
• The organization and ordering of the main text is not well structured; it is not arranged by functional modules or other logic, so it is not suitable for systematic study, but can be used for quick reference.

Exercises

1. Fork the FreeBSD source code repository, fix a minor issue in the documentation, generate a diff file, and submit it through the code review process.
2. Analyze the differences between FreeBSD and Linux kernel contribution mechanisms, and discuss their impact on community participation barriers.
3. Improve the BSD libc documentation generation script, reorganize the document structure by functional modules, and generate a new PDF document.