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.
Where to Find Open Tasks
1.1 Ongoing Programmer Tasks
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”.
- Read the FreeBSD problem reports mailing list. There may be a problem you can comment constructively on, or with patches you can test. You could even try to fix one of the problems yourself.
- If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder.
- Move contributed software to
src/contribin the source tree.
- Make sure code in
src/contribis up to date.
- Build the source tree with extra warnings enabled and clean up the warnings. A list of build warnings can also be found from our CI by selecting a build and checking “LLVM/Clang Warnings”.
- Fix warnings for ports which do deprecated things like using
- If you have contributed any ports where you had to make FreeBSD-specific changes, send your patches back to the original authors (this will make your life easier when they bring out the next version).
- Get copies of formal standards like POSIX®. Compare FreeBSD’s behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able to, figure out how to fix it and include a patch in the PR.
1.2 Working Through the PR Database
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.
1.3 Ongoing Ports Tasks
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:
- Create a new port for a cool or useful software.
- Adopt an unmaintained port and become the maintainer.
- If you have created or adopted a port, be aware of what you need to do as a maintainer. Consider reading through the maintainer responsibilities.
- When you are looking for a quick challenge you could fix a bug or a broken port.
1.4 Pick One of the Items From the Ideas Page
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.
Ways to Contribute to The System
After identifying a task to work on, there are a few ways to assist with the operating system itself.
2.1 Submitting Bug Reports and General Commentary
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.
2.2 Submitting Changes to Existing Source Code
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 oldfile newfile
% 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.
2.3 New Code or Major Value-Added Packages
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.
Contributing to Ports
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.
3.1 Adopting Unmaintained Ports
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.
3.2 Finding and Fixing a Broken Port
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.
3.3 How to Adopt the Port
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.
3.4 Keep Your Ports up to Date
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.
- Watch for updates: Monitor the upstream vendor for new versions, updates and security fixes for the software. Announcement mailing lists or news web pages are useful for doing this. Sometimes users will contact you and ask when your port will be updated. If you are busy with other things, or for any reason just cannot update it at the moment, ask if they will help you by submitting an update. You may also receive automated email from the
FreeBSD Ports Version Checkinforming you that a newer version of your port’s distfile is available. More information about that system (including how to stop future emails) will be provided in the message.
- Incorporate changes: When they become available, incorporate the changes into the port. You need to be able to generate a patch between the original port and your updated port.
- Review and test: Thoroughly review and test your changes:
- Build, install and test your port on as many platforms and architectures as you can. It is common for a port to work on one branch or platform and fail on another.
- Make sure your port’s dependencies are complete. The recommended way of doing this is by installing your own ports tinderbox.
- Check that the packing list is up to date. This involves adding in any new files and directories and removing unused entries.
- Verify your port using portlint(1) as a guide.
- Consider whether changes to your port might cause any other ports to break. If this is the case, coordinate the changes with the maintainers of those ports. This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a
PORTREVISIONbump so that they will automatically be upgraded by automated tools such as portmaster or portupgrade(1).
- Submit changes: Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated one. Note: Please do not submit a shar(1) archive of the entire port; instead, use diff(1)
-ruN. In this way, committers can much more easily see exactly what changes are being made.
- Wait: At some stage a committer will deal with your PR. It may take minutes, or it may take weeks — so please be patient. If you don’t receive feedback, it may simply that the committer had none, or that it was missed.
- Give feedback: If a committer finds a problem with your changes, they will most likely refer it back to you. A prompt response will help get your PR committed faster, and is better for maintaining a thread of conversation when trying to resolve any problems.
- And Finally: Your changes will be committed and your port will have been updated. The PR will then be closed by the committer.
3.5 Ensure Your Ports Continue to Build Correctly
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:
- Watch for build failures: Check your mail for mail from
pkg-fallout@FreeBSD.organd the distfiles scanner to see if any of the port which are failing to build are out of date.
- Collect information: Once you are aware of a problem, collect information to help you fix it. Build errors reported by
pkg-falloutare accompanied by logs which will show you where the build failed. If the failure was reported to you by a user, ask them to send you information which may help in diagnosing the problem, such as:
- Build logs
- The commands and options used to build the port (including options set in
- A list of packages installed on their system as shown by pkg-info(8)
- The version of FreeBSD they are running as shown by uname(1)
- When their ports collection was last updated
- When their ports tree and
INDEXwas last updated
- Investigate and find a solution: Unfortunately there is no straightforward process to follow to do this. If you are stuck, ask for help! The FreeBSD ports mailing list is a good place to start, and the upstream developers are often very helpful.
- Submit changes: Just as with updating a port, you should now incorporate changes, review and test, submit your changes in a PR, and provide feedback if required.
- Send patches to upstream authors: In some cases, you will have to make patches to the port to make it run on FreeBSD. Some (but not all) upstream authors will accept such patches back into their code for the next release. If so, this may even help their users on other BSD-based systems as well and perhaps save duplicated effort. Please consider sending any applicable patches to the authors as a courtesy.
3.6 Investigate Bug Reports and PRs Related to Your Port
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:
- Respond to bug reports: Bugs may be reported to you through email via the Problem Report database. Bugs may also be reported directly to you by users. You should respond to PRs and other reports within 14 days, but please try not to take that long. Try to respond as soon as possible, even if it is just to say you need some more time before you can work on the PR. If you have not responded after 14 days, any committer may commit from a PR that you have not responded to via a
- Collect information: If the person reporting the bug has not also provided a fix, you need to collect the information that will allow you to generate one. If the bug is reproducible, you can collect most of the required information yourself. If not, ask the person who reported the bug to collect the information for you, such as:
- A detailed description of their actions, expected program behavior and actual behavior
- Copies of input data used to trigger the bug
- Information about their build and execution environment — for example, a list of installed packages and the output of env(1)
- Core dumps
- Stack traces
- Eliminate incorrect reports: Some bug reports may be incorrect. For example, the user may have simply misused the program; or their installed packages may be out of date and require updating. Sometimes a reported bug is not specific to FreeBSD. In this case report the bug to the upstream developers. If the bug is within your capabilities to fix, you can also patch the port so that the fix is applied before the next upstream release.
- Find a solution: As with build errors, you will need to sort out a fix to the problem. Again, remember to ask if you are stuck!
- Submit or approve changes: Just as with updating a port, you should now incorporate changes, review and test, and submit your changes in a PR (or send a follow-up if a PR already exists for the problem). If another user has submitted changes in the PR, you can also send a follow-up saying whether or not you approve the changes.
3.7 Providing Support
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:
- Submit a PR or send you patches to update your port
- Investigate and perhaps provide a fix to a PR
- Otherwise submit changes to your port
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.
3.8 Resources for Ports Maintainers and Contributors
The Porter’s Handbook is your hitchhiker’s guide to the ports system. Keep it handy!
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
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.
Other Ways to Contribute
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.