6. Conventions and Traditions

As a new developer there are a number of things you should do first. The first set is specific to committers only. (If you are not a committer, e.g., have GNATS-only access, then your mentor needs to do these things for you.)

6.1. Guidelines for Committers


The .ent, .xml, and .xml files listed below exist in the FreeBSD Documentation Project SVN repository at svn.FreeBSD.org/doc/.

If you have been given commit rights to one or more of the repositories:

Steps for New Committers
  • Add your author entity to head/share/xml/authors.ent; this should be done first since an omission of this commit will cause the next commits to break the doc/ build.

    This is a relatively easy task, but remains a good first test of your version control skills.


    New files that do not have the FreeBSD=%H svn:keywords property will be rejected when attempting to commit them to the repository. Be sure to read Section 5.3.7, “Adding and Removing Files” regarding adding and removing files, in addition to verifying that ~/.subversion/config contains the necessary "auto-props" entries from auto-props.txt mentioned there.


    Do not forget to get mentor approval for these patches!

  • Add yourself to the Developers section of the Contributors List (head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml) and remove yourself from the Additional Contributors section (head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml). Please note that entries are sorted by last name.

  • Add an entry for yourself to head/share/xml/news.xml. Look for the other entries that look like A new committer and follow the format.

  • You should add your PGP or GnuPG key to head/share/pgpkeys (and if you do not have a key, you should create one). Do not forget to commit the updated head/share/pgpkeys/pgpkeys.ent and head/share/pgpkeys/pgpkeys-developers.xml. Please note that entries are sorted by last name.

    Dag-Erling C. Smørgrav has written a shell script (head/share/pgpkeys/addkey.sh) to make this extremely simple. See the README file for more information.


    It is important to have an up-to-date PGP/GnuPG key in the Handbook, since the key may be required for positive identification of a committer, e.g., by the FreeBSD Administrators for account recovery. A complete keyring of FreeBSD.org users is available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt.

  • Add an entry for yourself to src/share/misc/committers-repository.dot, where repository is either doc, ports or src, depending on the commit privileges you obtained.

  • Some people add an entry for themselves to ports/astro/xearth/files/freebsd.committers.markers.

  • Some people add an entry for themselves to src/usr.bin/calendar/calendars/calendar.freebsd.

  • If you already have an account at the FreeBSD wiki, make sure your mentor moves you from the Contributors group to the Developers group. Otherwise, consider signing up for an account so you can publish projects and ideas you are working on.

  • Once you get access to the wiki, you may add yourself to the How We Got Here, Irc Nicks, and Dogs of FreeBSD pages.

  • If you subscribe to svn-src-all, svn-ports-all or svn-doc-all, you will probably want to unsubscribe to avoid receiving duplicate copies of commit messages and their followups.


All src commits should go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. No major new features or high-risk modifications should be made to the FreeBSD-STABLE branch.

6.2. Guidelines for Everyone

Whether or not you have commit rights:

  • Introduce yourself to the other developers, otherwise no one will have any idea who you are or what you are working on. You do not have to write a comprehensive biography, just write a paragraph or two about who you are and what you plan to be working on as a developer in FreeBSD. (You should also mention who your mentor will be). Email this to the FreeBSD developers mailing list and you will be on your way!

  • Log into hub.FreeBSD.org and create a /var/forward/user (where user is your username) file containing the e-mail address where you want mail addressed to yourusername@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to the FreeBSD committer's mailing list and the FreeBSD developers mailing list. Really large mailboxes which have taken up permanent residence on hub often get accidentally truncated without warning, so forward it or read it and you will not lose it.

    Due to the severe load dealing with SPAM places on the central mail servers that do the mailing list processing the front-end server does do some basic checks and will drop some messages based on these checks. At the moment proper DNS information for the connecting host is the only check in place but that may change. Some people blame these checks for bouncing valid email. If you want these checks turned off for your email you can place a file named .spam_lover in your home directory on freefall.FreeBSD.org to disable the checks for your email.


If you are a developer but not a committer, you will not be subscribed to the committers or developers mailing lists; the subscriptions are derived from the access rights.

6.3. Mentors

All new developers also have a mentor assigned to them for the first few months. Your mentor is responsible for teaching you the rules and conventions of the project and guiding your first steps in the developer community. Your mentor is also personally responsible for your actions during this initial period.

For committers: until your mentor decides (and announces with a commit to mentors) that you have learned the ropes and are ready to commit on your own, you should not commit anything without first getting your mentor's review and approval, and you should document that approval with an Approved by: line in the commit message.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.