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
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.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 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 firstname.lastname@example.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
~.ssh/identity and a
~.ssh/identity.pub file. The
is a secret key, which should only be readable by me and must be
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"
# ssh freefall.freebsd.org
Enter passphrase for RSA key 'email@example.com':
Last login: Sat Jan 5 14:00:21 2002 from cc806427-a.stcl1
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
The Regents of the University of California. All rights reserved.
FreeBSD 4.4-STABLE (FREEFALL) #2: Sun Nov 25 15:58:20 PST 2001
Welcome to Freefall
Unauthorized access is strictly prohibited.
Report any problems/issues to firstname.lastname@example.org
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.
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
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:
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.
Michael W. Lucas
Read more Big Scary Daemons columns.
Return to the BSD DevCenter.
Copyright © 2009 O'Reilly Media, Inc.