Committer's Guide

ssh(1) is required to connect to the project hosts. For more information, see Section 15, “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 reset a Kerberos password in the FreeBSD cluster 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.

It is assumed that you are already familiar with the basic operation of Subversion. If not, start by reading the Subversion Book.

# pkg install subversion

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

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

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

Host svn.freebsd.org
	User jarjar

% svn help

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

% svn checkout --depth=immediates svn+ssh://svn.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://svn0.us-west.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

% cp foo.c bar.c
% svn add 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://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/stable/8

% svn checkout --depth=immediates svn+ssh://svn.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/ 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://svn.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://svn.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 --parents add

% svn cp svn+ssh://svn.freebsd.org/base/vendor/pf/dist svn+ssh://svn.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://svn.freebsd.org/base/vendor/pf/dist .

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

% svn diff --no-diff-deleted --old=svn+ssh://svn.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://svn.freebsd.org/base/ROADMAP.txt

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

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

% rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .

% rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .

% fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.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://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/projects/spif

% cd copy_of_spif
% svn merge svn+ssh://svn.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 .

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.

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

As well as including an informative message with each commit you may need to include some additional information.

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:

...

	    PR:                    12345
	    Submitted by:	   John Smith <[email protected]>

...

	    Reviewed by:       -arch

...

	    Approved by:	    abc (maintainer)

...

	    Obtained from:      OpenBSD

...

MFC after:      2 weeks

In many cases you may need to combine some of these.

Consider the situation where a user has submitted a PR containing code from the NetBSD project. You are looking at the PR, but it is not an area of the tree you normally work in, so you have decided to get the change reviewed by the arch mailing list. Since the change is complex, you opt 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 <[email protected]>
Reviewed by:        -arch
Obtained from:      NetBSD
MFC after:          1 month
Relnotes:           yes

Currently the FreeBSD Project suggests and uses the following text as the preferred license scheme:

/*-
 * Copyright (c) [year] [your name]
 * All rights reserved.
 *
 * 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 <[email protected]> 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 <[email protected]> has decided to keep an archive of them. Whenever the FreeBSD project is granted a special license we require the Core Team <[email protected]> to be notified. Any developers involved in arranging such a license grant, please send details to the Core Team <[email protected]> including:

Once the Core Team <[email protected]> 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 <[email protected]>.

If you are 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. If you see 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. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the repository-committers mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you should contact the listed MAINTAINER in the Makefile. For other parts of the repository, if you are unsure who the active maintainer might be, it may help to 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 your queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it.

If you are unsure about a commit for any reason at all, have it reviewed by -hackers before committing. Better to have it flamed then and there rather than when it is part of the repository. If you do happen to commit something which results in controversy erupting, you may also wish 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 someone you disagree with. If they see a different solution to a problem than you, or even a different problem, it is not because they are stupid, because they have questionable parentage, or because they are trying to destroy your hard work, personal image, or FreeBSD, but simply 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 you are not sure 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 you should 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 entering a new bug. Choose Supporting Services as the Product, and Bug Tracker as the Component.

You can find out more about Bugzilla at:

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

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 you should be able to use ssh-add(1) for authentication once per session. This will prompt you for your private key's pass phrase, and then store it in your authentication agent (ssh-agent(1)). If you no longer wish to have your key stored in the agent, issuing ssh-add -d will remove it.

Test by doing something such as ssh freefall.FreeBSD.org ls /usr.

For more information, see security/openssh, 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: http://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.

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, in order to identify various problems on the FreeBSD website.