Here's a quick summary of what I do to update a port. This will be enough for simple updates. For more complicated ones, you may have to find your own way. This guide is only directed toward non-library ports, except for python ports. I've never updated a perl or ruby port, so some details may not apply. (I simply don't know).

Collect some tools

I created a bunch of tools to help me with ports work. They are published on github. You can remove or update the portscp script if it suits your need.

Put two things in /etc/mk.conf :

SUDO=/usr/bin/doas
PATCH_DEBUG=Yes

The first one allows you do do all the work with your user, becoming root as needed. Such easy, much secure, wow.

Keep your ports tree clean

cd /usr/ports && mkdir mystuff

Then you'll have to create the category directory of the port you want to update. If you want to update devel/foo ports :

cd /usr/ports/mystuff && mkdir devel && cd devel
# copy the ports directory
cp -R /usr/ports/devel/foo .
cd foo

Now you have a directory you can safely trash.

Find out what you're going to need

Take a look at the Changelog from upstream and see what sort of developments there have been. You should check, also, whether the port needs new dependencies that you may have to port first. For python ports, I usually read setup.py and look for "req," and then I follow the white rabbit to see where it leads.

Update the port

First, bump the version in Makefile to the one you to which you're updating. Then, run make makesum. It will fetch the distfiles (upstream code) and update distinfo (size and checksum of the distfiles).

If there's a REVISION, remove it (or them, in case of subpackages), but don't touch EPOCH.

Check whether the patch needed to be regenerated. (That's why PATCH_DEBUG is needed):

make patch

and look for "offset". If there is some, you have to run make update-patches (and possibly edit the file getting patched). You can run portsdiff to verify that there were no substitutions made that you will have to undo by hand.

Simulate the port installation

Just run:

make fake

If it doesn't succeed, you'll have to debug this. I have no special advice for that.

Update the plist if needed

For non-python ports:

make update-plist

For a python2-only port:

make REVISION=999 plist

For a python ports with a py3 flavor:

portspy3plist

It sets everything how it needs to be thanks to a regex (so be careful ;)).

Use portsdiff again to check for anything unusual. make plist is not perfect; you'll probably have to correct it by hand.

Check WANTLIB is ok

portsldc

If there's something missing, one possible solution is to comment everything then run portsldc again and copy the WANTLIB += lines.

SHARED_LIBS ?

Just follow the FAQ, it's very clear and easy.

What I usually do is just make fake in both /usr/ports/foo/bar and /usr/ports/mystuff/foo/bar, and then cd /usr/ports/pobj/whatever-before-update/fake-amd64/usr/local/lib run the nm command from the FAQ, redirecting the output into /tmp/before and doing the same cd /usr/ports/pobj/whatever-after-update/fake-amd64/usr/local/lib then run nm again, redirecting the output into /tmp/after and finally diff -up /tmp/before /tmp/after should show you whether functions were added or removed.

Test it

If the port comes with a test suite, the best thing you can do is to run it on the port before and after the update to see the changes. A failing test doesn't mean the software won't work, and a working test doesn't mean the software will work either, but these results can be interesting.

Also, the goal of a port is that the software be usable, so you can either test it yourself, or you can ask on ports@ for users of this software to test it for you.

If the port is used by other ports, you'd better verify that your update doesn't break anything. How can you tell which ports depend on the one you're updating? I created a small python script that uses sqlports to find them. It's called "showvictims.py" for obvious reasons and you can find it on the github repository I linked at the beginning of this article.

Comparing Makefiles

grep is my friend. I mean if I see something in particular, I won't try to be clever. I just search to see whether a similar case exists in the ports tree (hint: it surely did) and just do the same thing. Feel free to do the same.

Everything looks good

When you're satisfied with the status of the port, just send the update to ports@ (if there is a maintainer, you must at least Cc them ). Wait for a committer to pick it up. If there has been no progress after a week, send a ping to the mailing list.

Why this guide and not the OpenBSD FAQ?

Because they're my personal notes. You can send a diff to ports@ if you want to.