Committer's Guide

ssh(1) is required to connect to the project hosts. For more information, see Section 16, “SSH Quick-Start Guide”.

Useful links:

Cryptographic keys conforming to the OpenPGP (Pretty Good Privacy) standard are used by the FreeBSD project to authenticate committers. Messages carrying important information like public SSH keys can be signed with the OpenPGP key to prove that they are really from the committer. See PGP & GPG: Email for the Practical Paranoid by Michael Lucas and http://en.wikipedia.org/wiki/Pretty_Good_Privacy for more information.

The FreeBSD cluster requires a Kerberos password to access certain services. The Kerberos password also serves as the LDAP web password, since LDAP is proxying to Kerberos in the cluster. Some of the services which require this include:

To create a new Kerberos account in the FreeBSD cluster, or to reset a Kerberos password for an existing account using a random password generator:

% ssh kpasswd.freebsd.org

A Kerberos password can also be set manually by logging into freefall.FreeBSD.org and running:

% kpasswd

The FreeBSD repository has a number of components which, when combined, support the basic operating system source, documentation, third party application ports infrastructure, and various maintained utilities. When FreeBSD commit bits are allocated, the areas of the tree where the bit may be used are specified. Generally, the areas associated with a bit reflect who authorized the allocation of the commit bit. Additional areas of authority may be added at a later date: when this occurs, the committer should follow normal commit bit allocation procedures for that area of the tree, seeking approval from the appropriate entity and possibly getting a mentor for that area for some period of time.

Commit bits allocated prior to the development of the notion of areas of authority may be appropriate for use in many parts of the tree. However, common sense dictates that a committer who has not previously worked in an area of the tree seek review prior to committing, seek approval from the appropriate responsible party, and/or work with a mentor. Since the rules regarding code maintenance differ by area of the tree, this is as much for the benefit of the committer working in an area of less familiarity as it is for others working on the tree.

Committers are encouraged to seek review for their work as part of the normal development process, regardless of the area of the tree where the work is occurring.

New committers are assumed to already be familiar with the basic operation of Subversion. If not, start by reading the Subversion Book.

# pkg install subversion

% svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src

% svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc

% svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports

Host repo.freebsd.org
	User jarjar

% svn help

% svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src

% svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base

% svn up --set-depth=infinity base/head
% svn up --set-depth=immediates base/release base/releng base/stable

% svn up --set-depth=infinity base/stable/7

% svn up --set-depth=infinity base/stable/7/sys
% svn up --set-depth=infinity base/stable/7

% svn co https://svn.FreeBSD.org/base/head /usr/src

% svn update
% svn update -r12345

% svn status

% svn status --show-updates

% svn commit

% svn commit lib/libfetch usr/bin/fetch

% /usr/ports/Tools/scripts/psvn commit

% svn add foo

% svn remove foo

% mkdir bar
% svn add bar

% svn mkdir bar

% svn rm bar

% svn copy foo.c bar.c

% svn move foo.c bar.c

% svn diff -r179453:179454 ROADMAP.txt

% svn diff -c179454 .

% svn resolved foo

% svn resolve --accept=working foo

% cd ~/freebsd
% svn update --set-depth=immediates .

% svn update --set-depth=infinity head

% svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8

% svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base
% cd base
% svn update --set-depth=infinity head
% svn copy head stable/8
% svn commit stable/8

% svn merge -c r123456 ^/head/ stable/11
% svn commit stable/11

% svn merge -c r123456 ^/stable/11  releng/11.0
% svn commit releng/11.0

% svn merge -c r123456 ^/head/ checkout
% svn commit checkout

% svn merge -c r123456 ^/stable/10 releng/10.0

% cd stable/7
% svn up --set-depth=infinity

% cd stable/6/contrib/openpam
% svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam

% svn propget svn:mergeinfo -R $target
$target - /head/$source:$P,$Q

% svn merge -c$R $FSVN/head/$source $target

% svn propget svn:mergeinfo -R $target
$target - head/$source:$P,$Q,$R

% svn propget svn:mergeinfo -R stable/9/share/man/man4

% svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4
--- Merging r238987 into 'stable/9/share/man/man4':
U    stable/9/share/man/man4/netmap.4
--- Recording mergeinfo for merge of r238987 into
'stable/9/share/man/man4':
 U   stable/9/share/man/man4

% svn commit stable/9/share/man/man4

% cd vendor/pf/dist/contrib/pf
% svn mv $(svn list) ../..
% cd ../..
% svn rm contrib
% svn propdel -R svn:mergeinfo .
% svn commit

% svn propdel svn:keywords -R .
% svn commit

% cd head/contrib/pf
% svn merge --record-only svn+ssh://repo.freebsd.org/base/vendor/pf/dist@180876 .
% svn commit

% cd vendor/pf/dist
% svn list -R | grep -v '/$' | sort >../old
% cd ../pf-4.3
% find . -type f | cut -c 3- | sort >../new

% cd vendor/pf/pf-4.3
% tar cf - . | tar xf - -C ../dist
% cd ../dist
% comm -23 ../old ../new | xargs svn rm
% comm -13 ../old ../new | xargs svn add --parents

% svn cp svn+ssh://repo.freebsd.org/base/vendor/pf/dist svn+ssh://repo.freebsd.org/base/vendor/pf/4.3

% cd	vendor/pf
% svn cp dist 4.3
% svn propdel svn:mergeinfo -R 4.3

% cd head/contrib/pf
% svn up
% svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/vendor/pf/dist .

% svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/sendmail
% cd sendmail
% svn merge -c r261190 '^/vendor/sendmail/dist' .

% svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/vendor/pf/dist --new=.

% svn co --depth immediates $FSVN/vendor
% cd vendor
% svn mkdir byacc
% svn mkdir byacc/dist

% svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115

% svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc

% svn merge -r179454:179453 ROADMAP.txt
% svn commit

% svn merge -c -179454 ROADMAP.txt
% svn commit

% svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt

% svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454
% svn commit

% svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base

% tar xf svnmirror-base-r261170.tar.xz
% svnsync sync file:///home/svnmirror/base

% svn proplist -v --revprop -r 0 file:///home/svnmirror/base

% svn propset fbsd:notbinary yes foo.data

% svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif

% cd copy_of_spif
% svn merge svn+ssh://repo.freebsd.org/base/head
% svn commit

Host *
ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
ControlMaster auto
ControlPersist yes

mkdir ~/.ssh/sockets

% svn propdel -R svn:keywords .
% svn revert -R .

freebsd-sponsored-by = The FreeBSD Foundation
freebsd-mfc-after = 2 weeks

There are a number of things to do as a new developer. The first set of steps is specific to committers only. These steps must be done by a mentor for those who are not committers.

sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd
smtp_use_tls = yes

yourusername@FreeBSD.org  [smtp.freebsd.org]:587

[smtp.freebsd.org]:587          yourusername:yourpassword

smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps
smtpd_sender_restrictions = reject_known_sender_login_mismatch

yourusername@FreeBSD.org yourlocalusername

Code review is one way to increase the quality of software. The following guidelines apply to commits to the head (-CURRENT) branch of the src repository. Other branches and the ports and docs trees have their own review policies, but these guidelines generally apply to commits requiring review:

Sometimes code reviews will take longer than you would hope for, especially for larger features. Accepted ways to speed up review times for your patches are:

Developers should participate in code reviews as both reviewers and reviewees. If someone is kind enough to review your code, you should return the favor for someone else. Note that while anyone is welcome to review and give feedback on a patch, only an appropriate subject-matter expert can approve a change. This will usually be a committer who works with the code in question on a regular basis.

In some cases, no subject-matter expert may be available. In those cases, a review by an experienced developer is sufficient when coupled with appropriate testing.

This section contains some suggestions and traditions for how commit logs are formatted.

As well as including an informative message with each commit, some additional information may be needed.

This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information.

The key words or phrases are:

Approved by: username-of-mentor (mentor)

Approved by: re (username)

...

	    PR:                    12345
	    Submitted by:	   John Smith <John.Smith@example.com>

...

	    Reviewed by:       -arch

...

	    Approved by:	    abc (maintainer)

...

	    Obtained from:      OpenBSD

...

MFC after:      2 weeks

It is often necessary to combine these.

Consider the situation where a user has submitted a PR containing code from the NetBSD project. Looking at the PR, the developer sees it is not an area of the tree they normally work in, so they have the change reviewed by the arch mailing list. Since the change is complex, the developer opts to MFC after one month to allow adequate testing.

The extra information to include in the commit would look something like

PR:                 54321
Submitted by:       John Smith <John.Smith@example.com>
Reviewed by:        -arch
Obtained from:      NetBSD
MFC after:          1 month
Relnotes:           yes

The FreeBSD Project's full license policy can be found at https://www.FreeBSD.org/internal/software-license.html. The rest of this section is intended to help you get started. As a rule, when in doubt, ask. It is much easier to give advice than to fix the source tree.

The FreeBSD Project suggests and uses this text as the preferred license scheme:

/*-
 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
 *
 * Copyright (c) [year] [your name]
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * [id for your version control system, if any]
 */

The FreeBSD project strongly discourages the so-called "advertising clause" in new code. Due to the large number of contributors to the FreeBSD project, complying with this clause for many commercial vendors has become difficult. If you have code in the tree with the advertising clause, please consider removing it. In fact, please consider using the above license for your code.

The FreeBSD project discourages completely new licenses and variations on the standard licenses. New licenses require the approval of the Core Team <core@FreeBSD.org> to reside in the main repository. The more different licenses that are used in the tree, the more problems that this causes to those wishing to utilize this code, typically from unintended consequences from a poorly worded license.

Project policy dictates that code under some non-BSD licenses must be placed only in specific sections of the repository, and in some cases, compilation must be conditional or even disabled by default. For example, the GENERIC kernel must be compiled under only licenses identical to or substantially similar to the BSD license. GPL, APSL, CDDL, etc, licensed software must not be compiled into GENERIC.

Developers are reminded that in open source, getting "open" right is just as important as getting "source" right, as improper handling of intellectual property has serious consequences. Any questions or concerns should immediately be brought to the attention of the core team.

Various software or data exist in the repositories where the FreeBSD project has been granted a special licence to be able to use them. A case in point are the Terminus fonts for use with vt(4). Here the author Dimitar Zhekov has allowed us to use the "Terminus BSD Console" font under a 2-clause BSD license rather than the regular Open Font License he normally uses.

It is clearly sensible to keep a record of any such license grants. To that end, the Core Team <core@FreeBSD.org> has decided to keep an archive of them. Whenever the FreeBSD project is granted a special license we require the Core Team <core@FreeBSD.org> to be notified. Any developers involved in arranging such a license grant, please send details to the Core Team <core@FreeBSD.org> including:

Once the Core Team <core@FreeBSD.org> is satisfied that all the necessary details have been gathered and are correct, the secretary will send a PGP-signed acknowledgement of receipt including the license details. This receipt will be persistently archived and serve as our permanent record of the license grant.

The license archive should contain only details of license grants; this is not the place for any discussions around licensing or other subjects. Access to data within the license archive will be available on request to the Core Team <core@FreeBSD.org>.

When working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. Working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. When modifying parts of the system which are maintained, formally, or informally, consider asking for review just as a developer would have before becoming a committer. For ports, contact the listed MAINTAINER in the Makefile.

To determine if an area of the tree is maintained, check the MAINTAINERS file at the root of the tree. If nobody is listed, scan the revision history to see who has committed changes in the past. An example script that lists each person who has committed to a given file along with the number of commits each person has made can be found at on freefall at ~eadler/bin/whodid. If queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it.

If there is any doubt about a commit for any reason at all, have it reviewed before committing. Better to have it flamed then and there rather than when it is part of the repository. If a commit does results in controversy erupting, it may be advisable to consider backing the change out again until the matter is settled. Remember, with a version control system we can always change it back.

Do not impugn the intentions of others. If they see a different solution to a problem, or even a different problem, it is probably not because they are stupid, because they have questionable parentage, or because they are trying to destroy hard work, personal image, or FreeBSD, but basically because they have a different outlook on the world. Different is good.

Disagree honestly. Argue your position from its merits, be honest about any shortcomings it may have, and be open to seeing their solution, or even their vision of the problem, with an open mind.

Accept correction. We are all fallible. When you have made a mistake, apologize and get on with life. Do not beat up yourself, and certainly do not beat up others for your mistake. Do not waste time on embarrassment or recrimination, just fix the problem and move on.

Ask for help. Seek out (and give) peer reviews. One of the ways open source software is supposed to excel is in the number of eyeballs applied to it; this does not apply if nobody will review code.

When unsure about something, whether it be a technical issue or a project convention be sure to ask. If you stay silent you will never make progress.

If it relates to a technical issue ask on the public mailing lists. Avoid the temptation to email the individual person that knows the answer. This way everyone will be able to learn from the question and the answer.

For project specific or administrative questions ask, in order:

Once your question is answered, if no one pointed you to documentation that spelled out the answer to your question, document it, as others will have the same question.

The FreeBSD Project utilizes Bugzilla for tracking bugs and change requests. Be sure that if you commit a fix or suggestion found in the PR database to close it. It is also considered nice if you take time to close any PRs associated with your commits, if appropriate.

Committers with non-FreeBSD.org Bugzilla accounts can have the old account merged with the FreeBSD.org account by following these steps:

You can find out more about Bugzilla at:

The FreeBSD Project utilizes Phabricator for code review requests. See the CodeReview wiki page for details.

Committers with non-FreeBSD.org Phabricator accounts can have the old account renamed to the FreeBSD.org account by following these steps:

Besides the repository meisters, there are other FreeBSD project members and teams whom you will probably get to know in your role as a committer. Briefly, and by no means all-inclusively, these are:

Now ssh-add(1) can be used for authentication once per session. It prompts for the private key's pass phrase, and then stores it in the authentication agent (ssh-agent(1)). Use ssh-add -d to remove keys stored in the agent.

Test with a simple remote command: ssh freefall.FreeBSD.org ls /usr.

For more information, see security/openssh-portable, ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), and scp(1).

For information on adding, changing, or removing ssh(1) keys, see this article.

All FreeBSD developers can obtain access to Coverity analysis results of all FreeBSD Project software. All who are interested in obtaining access to the analysis results of the automated Coverity runs, can sign up at Coverity Scan.

The FreeBSD wiki includes a mini-guide for developers who are interested in working with the Coverity® analysis reports: https://wiki.freebsd.org/CoverityPrevent. Please note that this mini-guide is only readable by FreeBSD developers, so if you cannot access this page, you will have to ask someone to add you to the appropriate Wiki access list.

Finally, all FreeBSD developers who are going to use Coverity® are always encouraged to ask for more details and usage information, by posting any questions to the mailing list of the FreeBSD developers.

Everyone involved with the FreeBSD project is expected to abide by the Code of Conduct available from https://www.FreeBSD.org/internal/code-of-conduct.html. As committers, you form the public face of the project, and how you behave has a vital impact on the public perception of it. This guide expands on the parts of the Code of Conduct specific to committers.

As noted, breaking some of these rules can be grounds for suspension or, upon repeated offense, permanent removal of commit privileges. Individual members of core have the power to temporarily suspend commit privileges until core as a whole has the chance to review the issue. In case of an “emergency” (a committer doing damage to the repository), a temporary suspension may also be done by the repository meisters. Only a 2/3 majority of core has the authority to suspend commit privileges for longer than a week or to remove them permanently. This rule does not exist to set core up as a bunch of cruel dictators who can dispose of committers as casually as empty soda cans, but to give the project a kind of safety fuse. If someone is out of control, it is important to be able to deal with this immediately rather than be paralyzed by debate. In all cases, a committer whose privileges are suspended or revoked is entitled to a “hearing” by core, the total duration of the suspension being determined at that time. A committer whose privileges are suspended may also request a review of the decision after 30 days and every 30 days thereafter (unless the total suspension period is less than 30 days). A committer whose privileges have been revoked entirely may request a review after a period of 6 months has elapsed. This review policy is strictly informal and, in all cases, core reserves the right to either act on or disregard requests for review if they feel their original decision to be the right one.

In all other aspects of project operation, core is a subset of committers and is bound by the same rules. Just because someone is in core this does not mean that they have special dispensation to step outside any of the lines painted here; core's “special powers” only kick in when it acts as a group, not on an individual basis. As individuals, the core team members are all committers first and core second.

FreeBSD is a highly portable operating system intended to function on many different types of hardware architectures. Maintaining clean separation of Machine Dependent (MD) and Machine Independent (MI) code, as well as minimizing MD code, is an important part of our strategy to remain agile with regards to current hardware trends. Each new hardware architecture supported by FreeBSD adds substantially to the cost of code maintenance, toolchain support, and release engineering. It also dramatically increases the cost of effective testing of kernel changes. As such, there is strong motivation to differentiate between classes of support for various architectures while remaining strong in a few key architectures that are seen as the FreeBSD “target audience”.

A few people who have access to the FreeBSD machines do not have commit bits. Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them). In particular, we recommend that you read:

As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project website to collect anonymized usage statistics regarding usage of the site. The information collected is valuable to the FreeBSD Documentation Project, to identify various problems on the FreeBSD website.