Updated: June 15, 2022

FreeBSD relies on the continued contributions of its user base to survive. Becoming involved is simple and there are a wide variety of tasks that users can contribute to.

A large and growing number of international contributors, of various ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated.

The FreeBSD project is responsible for the entire FreeBSD operating system environment, meaning a wide range of TODO tasks exist. To help contributing to the FreeBSD documentation, check out this guide on submitting and updating documentation.

This guide will focus on how programmers can contribute to the project. Please read through the following selection of tasks that may be needed.

Most of the tasks listed here require a considerable investment of time, an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for “weekend hackers”.

FreeBSD users can submit requests for enhancement and bug reports through to FreeBSD PR (problem report) database. The database contains many active programmer and non-programmer tasks, though not all tasks are required to be logged there. Look through the open problem reports, and see if anything there takes your interest. There is a wide range of tasks that may range from simple code reviews to much more complex requests that may not readily contain a fix.

Start with open problem reports that have not been assigned to anyone else. If there is an active PR that is assigned to someone else, but looks like something you would like to work on, email the person assigned to the task and ask if you can assist or take over the PR. They may already have a patch that they need to test, or benefit from your suggestions.

The Ports Collection contains a massive amount of content and as such, is always a perpetual work in progress. People are constantly needed to keep the collection up to date, and filled with high quality third party software.

Anyone can get involved, and there are lots of different ways to contribute. Contributing to ports is an excellent way to help “give back” something to the project. Whether you are looking for an ongoing role or a fun challenge for a rainy day, the project would love to have your help!

There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order:

The FreeBSD ideas page is regularly updated with items for programmers. Anyone looking to contribute to the FreeBSD Project can check it for tasks that they can assist with.

After identifying a task to work on, there are a few ways to assist with the operating system itself.

If you are submitting a specific change, you can submit the patch by using the bug submission form. This how to guide provides a step-by-step walkthrough for submitting a bug report.

If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. When patches are a lot larger than 20KB, consider compressing them prior to uploading them.

An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as “FreeBSD-CURRENT” which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT.

Working from older sources, unfortunately, means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the FreeBSD announcements mailing list and the FreeBSD-CURRENT mailing list lists, where discussions on the current state of the system take place.

Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the diff(1) command.

The preferred diff(1) format for submitting patches is the unified output format generated by diff -u.

% diff -u oldfile newfile

or

% diff -u -r -N olddir newdir

will generate a set of unified diffs for the given source file or directory hierarchy.

Once you have a set of diffs (which you may test with the patch(1) command), you should submit them for inclusion with FreeBSD as a bug report. Because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report.

If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to Core Team <core@FreeBSD.org> directly rather than submitting as a bug report. The Core Team <core@FreeBSD.org> reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary.

NOTE: Please refer to intro(9) and style(9) for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code.

In the case of a significant contribution, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or a publicly accessible git branch or repository. Running these large changes through Phabricator is also recommended.

When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. Copyleft licenses such as GPLv2 are sometimes permitted. The complete listing can be found on the core team licensing policy page.

Creating a port is a once-off task. Ensuring that a port is up to date and continues to build and run requires an ongoing maintenance effort. Maintainers are the people who dedicate some of their time to meeting these goals.

The foremost reason ports need maintenance is to bring the latest and greatest in third party software to the FreeBSD community. An additional challenge is to keep individual ports working within the Ports Collection framework as it evolves.

Taking over unmaintained ports is a great way to get involved. Unmaintained ports are only updated and fixed when somebody volunteers to work on them. There are a large number of unmaintained ports. A good idea is to start by adopting a port that you use regularly.

Unmaintained ports have their MAINTAINER set to ports@FreeBSD.org. A list of unmaintained ports and their current errors and problem reports can be seen at the FreeBSD Ports Monitoring System.

Some ports affect a large number of others due to dependencies. Generally, we want people to have some experience before they maintain these ports.

There are two really good places to find a port that needs some attention.

You can use the web interface to the Problem Report database to search through and view unresolved PRs. The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the sw-bug class is a good place to start).

The other place is the FreeBSD Ports Monitoring System. In particular look for unmaintained ports with build errors and ports that are marked BROKEN. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem.

Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. Otherwise create a new PR. Your changes will be reviewed and, if everything checks out, committed.

First, make sure you understand your responsibilities as a maintainer. Also read the Porter’s Handbook. Please do not commit yourself to more than you feel you can comfortably handle.

You may request maintainership of any unmaintained port as soon as you wish. Simply set MAINTAINER to your own email address and send a problem report (PR) with the change. If the port has build errors or needs updating, you may wish to include any other changes in the same PR. This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. Submitting PRs that fix build errors or update ports are the best ways to establish one.

File your PR with category ports and class change-request. A committer will examine your PR, commit the changes, and close the PR.

This section outlines the process to follow to keep your ports up to date.

This is an overview. More information about upgrading a port is available in the Porter’s Handbook.

FreeBSD only guarantees that the Ports Collection works on the -STABLE branches. In theory, you should be able to get by with running the latest release of each stable branch but if you can run the branch, that is even better.

Since the majority of FreeBSD installations run on PC-compatible machines (what is termed the i386 architecture), we expect you to keep the port working on that architecture. We prefer that ports also work on the amd64 architecture running native. It is completely fair to ask for help if you do not have one of these machines.

The usual failure modes for non–x86 machines are that the original programmers assumed that, for instance, pointers are ints, or that a relatively lax older gcc compiler was being used. More and more, application authors are reworking their code to remove these assumptions — but if the author is not actively maintaining their code, you may need to do this yourself.

These are the tasks you need to perform to ensure your port is able to be built:

FreeBSD-specific bugs are generally caused by assumptions about the build and runtime environments that do not apply to FreeBSD. You are less likely to encounter a problem of this type, but it can be more subtle and difficult to diagnose.

These are the tasks you need to perform to ensure your port continues to work as intended:

Part of being a maintainer is providing support — not for the software in general — but for the port and any FreeBSD-specific quirks and problems. Users may contact you with questions, suggestions, problems and patches. Most of the time their correspondence will be specific to FreeBSD.

Occasionally you may have to point users seeking general support to the appropriate resources. Less frequently you will encounter a person asking why the RPMs are not up to date or how can they get the software to run under Foo Linux. Take the opportunity to tell them that your port is up to date, and suggest that they try FreeBSD.

Sometimes users and developers will spend time assisting you and your port. They may:

In these cases, your main obligation is to respond in a timely manner. Again, the timeout for non-responsive maintainers is 14 days. After this period changes may be committed unapproved. They have taken the trouble to do this for you; so please try to at least respond promptly. Then review, approve, modify or discuss their changes with them as soon as possible.

The Porter’s Handbook is your hitchhiker’s guide to the ports system. Keep it handy!

The Problem Report database.

The FreeBSD Ports Monitoring System can show you cross-referenced information about ports such as build errors and problem reports. If you are a maintainer you can use it to check on the build status of your ports. As a contributor you can use it to find broken and unmaintained ports that need to be fixed.

The FreeBSD Ports distfile scanner can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their MASTER_SITES updated.

ports-mgmt/poudriere is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. Documentation is located at the poudriere github repository

portlint(1) is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. portlint is a simple heuristic application, so you should use it only as a guide. If portlint suggests changes which seem unreasonable, consult the Porter’s Handbook or ask for advice.

The FreeBSD ports mailing list is for general ports-related discussion. It is a good place to ask for help. You can subscribe, or read and search the list archives. Reading the archives of the FreeBSD ports bugs mailing list and the SVN commit messages for the ports tree for head/ may also be of interest.

If you are looking for something interesting to get started, the FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started.

The Junior Jobs page lists current projects that may interest people new to FreeBSD, these can be great way to acquaint oneself with the project.

Updated: June 2, 2021

One of the easiest ways to get involved with the FreeBSD Project is through the submission of bug reports. A bug report can be about any component of FreeBSD, including problems with the operating system programs, a mistake in the documentation, or a new feature that the submitter wishes to see incorporated.

General ideas and suggestions should be sent to the FreeBSD technical discussions mailing list. Bugs and specific changes can be submitted through the bug submission form.

This guide will focus on the process of using the Bugzilla form to report bugs and changes.

Before submitting a bug report, make sure that a bug report is the right course of action. There are still many cases where submitting a problem report is clearly not the right course of action, and will only serve to frustrate both the submitter and the developers. Below are a couple examples of cases which may not be worth a bug report:

As a general rule, the problem is not a bug if it can be expressed as a question (“How do I do X?” or “Where can I find Y”). While some cases might be worthy of a bug report, consider using the FreeBSD general questions mailing list to pose the question before submitting a bug report. This will help make sure that questions are filtered through the correct channels.

While submitting bug reports for ports or software not part of FreeBSD itself, consider the following:

While running into a bug that cannot be reproduced can be annoying, these rarely can be fixed. If the bug only occurred once and you cannot reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. Often these kinds of bugs are caused by a failing hard drive or overheated processor, try to rule these out before submitting a bug report.

The software that makes up FreeBSD is a collection of several different elements, making sure that the bug report is sent to the correct developers to ensure it is fixed quickly.

It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs. The Security Officer team maintains the list of supported versions.

Always do a background search before submitting a bug report. The bug may have already been reported or is being discussed on a mailing list. Therefore, you should check these places before submitting. These include:

Bug reports will use the bugzilla web form. To submit a bug report, an account will need to be created. Select the category that the bug falls under, then fill out the form.

The following fields will need to be filled out:

Once the problem report has been filed, you will receive a confirmation by email which will include the tracking number that was assigned to your problem report and a URL you can use to check its status. With a little luck, someone will take an interest in your problem and try to address it, or, as the case may be, explain why it is not a problem. You will be automatically notified of any change of status, and you will receive copies of any comments or patches someone may attach to your problem report’s audit trail.

If someone requests additional information from you, or you remember or discover something you did not mention in the initial report, please submit a follow up. The number one reason for a bug not getting fixed is lack of communication with the originator. The easiest way is to use the comment option on the individual PR’s web page, which you can reach from the PR search page.

If the problem report remains open after the problem has gone away, just add a comment saying that the problem report can be closed, and, if possible, explaining how or when the problem was fixed.

Sometimes there is a delay of a week or two where the problem report remains untouched, not assigned or commented on by anyone. This can happen when there is an increased problem report backlog or during a holiday season. When a problem report has not received attention after several weeks, it is worth finding a committer particularly interested in working on it.

There are a few ways to do so, ideally in the following order, with a few days between attempting each communication channel:

Remember that these people are volunteers, just like maintainers and users, so they might not be immediately available to assist with the problem report. Patience and consistency in the follow-ups is highly advised and appreciated. With enough care and effort dedicated to that follow-up process, finding a committer to take care of the problem report is just a matter of time.

Updated: February 5, 2022

Quality documentation is crucial to the success of FreeBSD, submitting documentation is one of the easiest ways to contribute to the project and anyone is welcome to submit! Willingness to contribute is the only membership requirement.

The first step to contribute is to subscribe to the FreeBSD documentation project mailing list. This is a fantastic resource for any questions or problems involving the documentation.

The working copy is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats.

FreeBSD documentation for commands and configuration files can be found within the manual page collection. These consist of two repositories: doc for books and articles, and src for operating system and manual pages. These repositories can contain multiple versions of documentation and source code.

In order to edit manual pages, src will need to be checked out separately.

FreeBSD documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user’s home directory.

A download of a working copy from the repository is called a clone, this can be done with git clone. For example, to checkout the latest version (head) of the documentation tree.

% git clone https://git.freebsd.org/doc.git ~./doc

And to checkout the source code for manual pages:

% git clone https://git.freebsd.org/src.git ~./src

The FreeBSD repository is frequently updated, even a short time after the initial checkout, changes may have already been made creating differences between the local working copy and the main FreeBSD repository. To update the local version, use git pull on the directory containing the local working copy. Getting into the habit of doing this often before editing document files will be helpful.

% cd ~/doc
% git pull --ff-only

Sometimes it turns out that changes were unnecessary, or the writer wants to start over. git restore can “reset” files to their unchanged form

% git restore filename

After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These diff files are produced by redirecting the output of git diff into a file:

% cd ~/doc
% git diff > filename

Give the file a meaningful name that identifies the contents. Thhttps://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/working-copy.htmlis will be important for identifying what type of change was made, and to what part of the tree.

If the diff file is to be submitted with the web “Submit a FreeBSD problem report” interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text.

Different types of output can be produced from a single AsciiDoc source file.

These are the tools used to build and install the FDP documentation.

There are three main types of Makefiles in the FreeBSD Documentation Project tree.

These Makefiles usually take this form: (Some contents have been removed for simplicity sake):

These Makefiles share a similar format to documentation Makefiles, however, no languages tag is used.

Here is an example of the second half of a website Makefile:

Most FDP documentation is written with AsciiDoc. This chapter explains what that means, how to read and understand the documentation source, and the techniques used. To get a complete reference of the AsciiDoctor capabilities please consult the Asciidoctor documentation. Some of the examples have been taken from the AsciiDoc Syntax Quick Reference.

AsciiDoctor supports six headings levels. If the document type is article only one level 0 (=) can be used. If the document type is book then there can be multiple level 0 (=) headings.

This is an example of headings in an article.

Paragraphs don’t require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. To create a new paragraph leave one blank line.

For example, this is a heading with two paragraphs.

AsciiDoctor supports a few types of lists, the most common are ordered and unordered. To get more information about lists, see AsciiDoc Syntax Quick Reference.

To create an ordered list use the . character.

For example, this is an ordered list.

And this would be rendered as.

To create an unordered list use the * character.

For example, this is an unordered list.

And this would be rendered as.

To point to another website the link macro should be used.

To point to another book or article the AsciiDoctor variables should be used. For example, if we are in the cups article and we want to point to ipsec-must these steps should be used.

We hope this guide has served as a brief introduction to the process of submitting documentation, programmers should also check out our guide on Contributing to FreeBSD as a Programmer.