How to Become a FreeBSD Committer

01/31/2002

I finally completed my FreeBSD book (Absolute BSD, due from No
Starch Press in a couple of months), and have some free time. I
started answering questions on mailing lists, and tried to refer
people to the FAQ. I remembered answering these same questions back
in 1997. And 1998. They should be in the FAQ by now, no?

But they weren't. At this point, I had two choices. I could compose
a caustic message to doc@FreeBSD.org and vent my frustration by
questioning the knowledge, skills, and ancestry of the FAQ
maintainers. A truly good caustic email message take quite a while to
write, as I tend to get carried away using language I don't really
have an excuse to use elsewhere. (How often do you really need words
like "pedicular," anyway?) While many people opt for this choice, and
I find it a rather entertaining hobby myself, I elected to go with
option B: fix the problem, and submit a patch.

Learning how to use the FreeBSD documentation tools really isn't
difficult; I was able to discuss it in
two pages in an earlier column. I made the changes I wanted in
the FAQ, built the FAQ to test them, and submitted them with send-pr.

To a committer, taking patches from PRs is a trivial annoyance.
Contributions are certainly appreciated, but they must be read,
evaluated, and tested. By accepting your code, the committer is
saying that your change is correct. If something is wrong with the
patch, he gets the flak. If you submit enough useful and correct PRs,
eventually some committer will get sick of taking care of your work
and will ask you if you want to be able to commit them yourself. This
process serves multiple purposes; after all, the FreeBSD community is
made up of people who do the work.
For committers, the work consists of creating useful and correct
patches. If you don't consistently and regularly create good patches,
there's no point in giving you commit access, now is there? Also, the
send-pr mechanism is useful to see if you work well within the FreeBSD
team. By the time you've submitted several dozen PRs, you'll either
work well with the FreeBSD team or everyone will understand that you
and the team just can't get along. Direct-commit access is either an
obvious next step, or an obviously bad move.

So I happily submitted PRs for a while. A few dozen PRs later, one
of the -doc committers sent me an email asking if I wanted a commit
bit. I said no. Committers have the ability to do a lot of things.
They can break the repository, or the upgrade process, or introduce
errors that can condemn thousands of people to long nights of
troubleshooting. I'm most interested in the FAQ, which is where
clueful new users check first. An error there is definitely highly
visible. Not to mention that I failed "plays well with others" all
through school.

About a dozen PRs later, however, a small group of committers ganged
up and said that I needed a commit bit. They insisted I wanted a
commit bit. My life would be incomplete without one. And just how
long did I intend to flood them with my PRs, anyway? I allowed myself
to be persuaded; while it's a serious responsibility, it's also pretty
durn cool. Here's a glimpse into the secret life of the FreeBSD
Committer.

Becoming a committer is fairly straightforward. Each part of FreeBSD
has someone responsible for approving committers. The core team
approves source-code committers. The portsmgr team approves ports
committers. Nik Clayton approves doc committers. In my case, Bruce
Mah approached Nik and asked him to issue me a commit bit. Nik
agreed, and sent me the nice little form letter asking for a variety
of information so he could set up an account on the FreeBSD systems.
He also confirmed that Bruce was my mentor.

Perhaps the most important part of being a new committer is your
mentor. Your mentor is an experienced committer who works in the same
part of the FreeBSD code tree that you do. He is responsible for
everything you do in the FreeBSD project. He answers your questions,
reviews your patches, points out rules and policies that you need to
know, and generally watches over you. When your mentor is comfortable
with one aspect of your work, he will turn you loose. As months pass,
you'll need your mentor less and less. For example, Bruce reviewed
all of my early patches. He gave me assignments that taught me how to
use the FreeBSD tools, such as closing my own PRs to learn about
GNATS. As he decided that I was able to do things without destroying
other people's work, he released me to make changes without having him
review them.

If I screw up, it will reflect badly on both myself and Bruce.
There's no real penalty except looking like an idiot, embarrassing my
mentor, and having to fix my own mess. Today, Bruce no longer reviews
my patches unless I ask him to -- he thinks I can be trusted to not do
anything egregiously stupid. He's still responsible for me, though.
(Poor guy.)

The first thing Bruce told me to do was look at the FreeBSD
Committers Guide. This discusses how the Project works, what
rules I must follow, and how to actually make CVS commits. If you're
seriously interested in becoming a committer, read this to see how
committers do what they do.

Once my mentor and I were settled, Nik asked for a username and an SSH
key. The username is simple: any name I want that nobody else is
using. I'm now mwlucas@FreeBSD.org. The SSH key required a bit of
learning, however. The FreeBSD servers do not use username/password
authentication, but instead use public-key cryptography with SSH. I
had to create a SSH key, consisting of the files identity and
identity.pub. I've used SSH for quite a while, but never bothered
with keys. Well, no time like the present to learn, is there? You
can generate a SSH keypair with ssh-keygen(1).

# ssh-keygen
Generating public/private rsa1 key pair.
Enter file in which to save the key (/home/mwlucas/.ssh/identity):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/mwlucas/.ssh/identity.
Your public key has been saved in /home/mwlucas/.ssh/identity.pub.
The key fingerprint is:
06:39:96:50:15:3b:55:ff:f3:71:fb:9b:12:e5:e0:99 mwlucas@pedicular.blackhelicopters.org
#

You can take the defaults for everything, but you must enter a
passphrase. A passphrase is a much longer password that can include
spaces. My passphrase is about eighty characters long, and contains
both alphanumerics and special characters. So, the command above gave
me a ~.ssh/identity and a ~.ssh/identity.pub file. The identity file
is a secret key, which should only be readable by me and must be
closely guarded. identity.pub is the public key, and I can hand that
out to any system I want. When a system combines the private key, the
public key, and the passphrase, the identity key is "unlocked" and I
am allowed to access the master FreeBSD source repository system. So
I sent the identity.pub file to Nik, who put it in my
freefall.FreeBSD.org home directory as .ssh/authorized_keys. Once he
did that, I was able to log in to what most people regard as "FreeBSD"
itself.

NOTE: .forward files do not work. To forward your mail login to
hub.freebsd.org and create a /var/forward/yourusername file that
contains a forwarding address.

freefall~;

I must admit that my heart skipped a beat there. After years of
hanging around the FreeBSD scene, the mysterious "freefall" opened
before me like King Tut's tomb. I mentioned this to Bruce, and he
told me that he was glad that he wasn't the only one who felt that
way.

So here I am. Now what?

I had some more FAQ patches. First, I sent them to Bruce for
evaluation. Once he approved them, I used scp(1) to transfer them up
to freefall. Following instructions in the committers' guide, I
checked out a copy of the FAQ in my home directory, and applied my
diff with patch(1). Finally, I ran a cvs diff -c and a cvs status to
confirm that my local copy of the FAQ was up-to-date in every respect,
except for my patch. Finally, I typed the scary command that gives
committers their name:

cvs commit

My preferred text editor popped up, with a template of a typical CVS
log message. My first commit looked a little odd, but that's because
the FreeBSD standard is to put the commit message at the top of the
file, not at the bottom, where the template puts it. Once I exit the
editor, my changes are incorporated into the repository and my commit
message is sent to cvs-all@FreeBSD.org.

Well, I'm now one of the elite. My power isn't quite life-and-death
over people, but I can now make their lives much more difficult. (As
if the potential damage these articles permit wasn't enough!) Of
course, if I do anything truly dumb, various other FreeBSD people will
have a very pointed talk with me. (The points would probably be
provided by, say, knives and broken bottles.)

You too can do this. If you submit decent patches, and you work well
with the FreeBSD team, you'll be offered a commit bit. If you don't
accept the commit bit, but continue submitting patches, one might be
forced down your throat. If you don't submit PRs, there's no way
you'll get a commit bit. The committers are the ones who do the work,
for very little reward. Despite my initial trepidation, I'm proud to
be one of them. Now, let's hope my Project work doesn't prove to be
pedicular.