Patching OpenBSD
2014-08-24
Recently, I've been trying to understand the ins and outs of CVS in order to be able to contribute to OpenBSD without messing up anything. I have sent a few patches to ports@, but anything complex was beyond my abilities until recently.
How does OpenBSD's contributing system work?
OpenBSD uses a tried and tested method of accepting contributions from users that has remained unchanged for many years - a mailing list. Anyone can send in a patch to ports@openbsd.org or tech@openbsd.org and it will be looked at by the people with commit access and (hopefully) committed into the tree.
But where's this "tree"? What is it? OpenBSD uses CVS as its version control system. While it is a bit old, they have their reasons for using it, so it's best not to complain. Essentially, all history is stored on the server, not locally, which is very different from how a distributed VCS would do it. It doesn't affect actual usage of CVS, though, so don't worry about it.
Checking out the source
From here on out, I'll assume you're trying to update a program in the ports tree you might use. The example program I'll be using is "editors/joe", which is Joe's Own Editor, a very simple editor inspired by Emacs and WordStar (yeah, it's not the newest editor either).
The first step is finding a nearby CVS repo. A good place to look is on this list. Pick one that's near you and export the CVSROOT variable where it says "CVSROOT=anoncvs@blahblah". For example, I'm in the UK, so I'll pick a server in Europe and export CVSROOT:
$ export CVSROOT=anoncvs@ftp5.eu.openbsd.org:/cvs
The next step is checking out the ports tree from the server:
# cd /usr
# cvs checkout ports
Now you have a fully updated ports tree in /usr/ports! Note that I didn't specify any flags: on OpenBSD, there is a default ~/.cvsrc that comes by default in every user's home. Mine looks like this:
# $OpenBSD: dot.cvsrc,v 1.1 2013/03/31 21:46:53 espie Exp $
#
diff -uNp
update -P
checkout -P
Making a patch
Now, you might want to find the file you want to change. In this example, it's in editors/joe, so lets go there in the ports tree:
# cd /usr/ports/editors/joe
I'm not going to explain how to edit Makefiles and update ports in OpenBSD, a guide for that already exists here. Instead, lets assume you already know how to make changes (and you will, after reading that guide).
# vi Makefile
**make some changes**
If you delete any files or add any files, you have to do cvs delete
<file> or cvs add <file> for the changes to be tracked properly. Do
this before making a patch in the next step.
Now you have to get the changes you just made into an email, which is
easy using cvs diff. Run cvs diff and redirect its output to a file
somewhere.
# cvs diff > /tmp/joe.diff
If you look at /tmp/joe.diff, you'll see that all the changes you made
have been recorded in that file, in the format used by patch(1). You
don't need to know how to apply the patch, that will be done by whoever
wants to try out your changes. For completion's sake, you do that by
running patch -p0 < /tmp/joe.diff in the right directory
(/usr/ports/editors/joe, in this case).
Mailing that patch to ports@
In case you don't know how mailing lists work, let me explain. You send an email to an address (in this case, ports@openbsd.org), and it is processed by the mail server and sent out to everyone subscribed to the list, who can then apply the patch.
In your email client, write a new message with the subject "UPDATE: joe 3.7 -> 3.8" (with the right versions, of course), to be sent to "ports@openbsd.org" and CC'ed to whoever was listed as the port maintainer in the Makefile. Write something short and descriptive in the body of the message, like this:
Hello ports@,
This is an update to joe which fixes this bug and that bug and adds a
useful feature.
OK?
In the rest of the message, paste your diff. It's easier for everyone if you just put your diff in the body of the message, because they can then just apply your email as the patch and everything will work out fine.
Now send the mail and wait.
If you get a response, take into consideration any criticism and send a new diff. If someone important (usually with an @openbsd.org email address) tells you it's OK, congratulations! They'll apply your patch, commit it to CVS and you'll have contributed to OpenBSD!