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 be focused on the process of using the Bugzilla form to report bugs and changes.

1. When to Submit a Bug Report:

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:

Questions:

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.

Ports/Other Software

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

  • Please do not submit problem reports that about updated versions of applications. Ports maintainers are automatically notified by portscout when a new version of an application becomes available. A patch to update that port to the newest version, however, would be welcome.
  • For unmaintained ports (MAINTAINER is ports@FreeBSD.org), a PR without an included patch is unlikely to get picked up by a committer. To become the maintainer of an unmaintained port, submit a PR with the request (patch preferred but not required).
Non Reproducible Bugs

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.

2. Who Should the Report be Filed to?

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.

  • Code in the base system that is written and maintained by FreeBSD contributors, such as the kernel, the C library, and the device drivers (categorized as kern); the binary utilities (bin); the manual pages and documentation (docs); and the web pages (www). All bugs in these areas should be reported to the FreeBSD developers.
  • Code in the base system that is written and maintained by others, and imported into FreeBSD and adapted. Examples include clang(1), and sendmail(8). Most bugs in these areas should be reported to the FreeBSD developers; but in some cases they may need to be reported to the original authors instead if the problems are not FreeBSD-specific.
  • Individual applications that are not in the base system but are instead part of the FreeBSD Ports Collection (category ports). Most of these applications are not written by FreeBSD developers; what FreeBSD provides is merely a framework for installing the application. Therefore, only report a problem to the FreeBSD developers when the problem is believed to be FreeBSD-specific; otherwise, report it to the authors of the software.

3. Extra Considerations

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:

  1. The FreeBSD Frequently Asked Questions (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning hardware compatibility, user applications, and kernel configuration.
  2. The mailing lists—if you are not subscribed, use the searchable archives on the FreeBSD website.
  3. Optionally, the entire web—use your favorite search engine to locate any references to the problem.
  4. Next, the searchable FreeBSD PR database (Bugzilla). Unless the problem is recent or obscure, there is a fair chance it has already been reported.
  5. Most importantly, attempt to see if existing documentation in the source base addresses your problem. For the base FreeBSD code, you should carefully study the contents of /usr/src/UPDATING on your system or the latest version at https://svnweb.freebsd.org/base/head/UPDATING?view=log. (This is vital information if you are upgrading from one version to another—especially if you are upgrading to the FreeBSD-CURRENT branch). However, if the problem is in something that was installed as a part of the FreeBSD Ports Collection, you should refer to /usr/ports/UPDATING (for individual ports) or /usr/ports/CHANGES (for changes that affect the entire Ports Collection). https://svnweb.freebsd.org/ports/head/UPDATING?view=log and https://svnweb.freebsd.org/ports/head/CHANGES?view=log are also available via svnweb.

4. Submitting the Bug Report

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:

  • Summary: A short and specific description of the bug. This will be used as the subject of the bug report email. Obscure summaries tend to be ignored.
  • Severity: Choose between one of Affects only me, Affects some people, or Affects many people. Make sure to be realistic with this and only mark it as Affects many people if it really does.
  • Component: Choose the appropriate category. Figure out what part of the system contains the bug. Remember, FreeBSD is a complete operating system, which installs both a kernel, the standard libraries, many peripheral drivers, and a large number of utilities (the “base system”). However, there are thousands of additional applications in the Ports Collection. Here’s a list of possible categories:
    1. If a problem is with the kernel, the libraries (such as standard C library libc), or a peripheral driver in the base system, in general you will use the kern category. (There are a few exceptions; see below). In general these are things that are described in section 2, 3, or 4 of the manual pages.
    2. If a problem is with a binary program such as sh(1) or mount(8), you will first need to determine whether these programs are in the base system or were added via the Ports Collection. If you are unsure, you can do whereis programname. FreeBSD’s convention for the Ports Collection is to install everything underneath /usr/local, although this can be overridden by a system administrator. For these, you will use the ports category (yes, even if the port’s category is www; see below). If the location is /bin, /usr/bin, /sbin, or /usr/sbin, it is part of the base system, and you should use the bin category. These are all things that are described in section 1 or 8 of the manual pages.
    3. If you believe that the error is in the startup (rc) scripts, or in some kind of other non-executable configuration file, then the right category is conf (configuration). These are things that are described in section 5 of the manual pages.
    4. If you have found a problem in the documentation set (articles, books, man pages) or website the correct choice is docs.
  • There are a few more specialized categories.
    • If the problem would otherwise be filed in kern but has to do with the USB subsystem, the correct choice is usb.
    • If the problem would otherwise be filed in kern but has to do with the threading libraries, the correct choice is threads.
    • If the problem would otherwise be in the base system, but has to do with our adherence to standards such as POSIX®, the correct choice is standards.
    • If you are convinced that the problem will only occur under the processor architecture you are using, select one of the architecture-specific categories: commonly i386 for Intel-compatible machines in 32-bit mode; amd64 for AMD machines running in 64-bit mode (this also includes Intel-compatible machines running in EMT64 mode); and less commonly arm or powerpc.
    • If you really do not know where the problem lies (or the explanation does not seem to fit into the ones above), use the misc category.
  • Version: Choose the environment where the bug was observed. Include the operating system and version, the version of the specific program or file where the bug occurred in the description below.
  • Description: Describe the bug you are experiencing. Unless you are absolutely certain, avoid speculation on what may be causing the issue. The description should include steps to replicate the issues, as well as any workarounds that you discovered. This is important because it may help other people with the same issue or help a developer figure out the cause.

5. Following Up

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:

  • Find the relevant FreeBSD mailing list for the problem report from the list in the Handbook and send a message to that list asking about assistance or comments on the problem report.
  • Join the relevant IRC channels. A partial listing is here: https://wiki.freebsd.org/IrcChannels. Inform the people in that channel about the problem report and ask for assistance. Be patient and stay in the channel after posting, so that the people from different time zones around the world have a chance to catch up.
  • Find committers interested in the problem that was reported. If the problem was in a particular tool, binary, port, document, or source file, check the SVN Repository. Locate the last few committers who made substantive changes to the file, and try to reach them via IRC or email. A list of committers and their emails can be found in the Contributors to FreeBSD article.

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.