Here's a quick summary of what I do to update a port. This will be enough for simple updates but for more complicated one, it won't and you'll have to find your way. This guide is only toward non-library ports, except if they're python ports. It means that I've never updated a perl or a ruby ports so things may not applied (I simply don't know).

Get some tools

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

Put two things in /etc/mk.conf :

SUDO=/usr/bin/doas
PATCH_DEBUG=Yes

First one is so you can do all of the work with your user and it will become root as needed. Such easy, much secure, wow.

Don't be a gipsy and keep your ports tree clean

cd /usr/ports && mkdir mystuff

Then you'll have the 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 your directory you can trash :)

See what you're going to take

Have a look to the Changelog from upstream, see if there has been much developments going in. Also check if the port needs new depends that you may need 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 with the one you want to update to. Then run make makesum, it will fetch the distfiles (upstream codes) 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 if 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 wasn't any substitution done that you have to undone by hand.

Simulate the port installation

Just run

make fake

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

Update the plist if needed

For a non-python ports

make update-plist

For a python2-only ports

make REVISION=999 plist

For a python ports with a py3 flavor :

portspy3plist

It makes everything as it needs to be thanks to a regex (so be careful ;)).

Again portsdiff to check that it's not 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 solution is it comment everything then run it 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 with redirecting the output in /tmp/before and doing the same cd /usr/ports/pobj/whatever-after-update/fake-amd64/usr/local/lib then again running nm with redirecting the output in /tmp/after and finally diff -up /tmp/before /tmp/after should show you if 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 evolution. A failing test doesn't say the software won't work and a working test doesn't say the software will work either, but it can be interesting.

Also the goal of a port is that the sotfware is usable by people so either you can test it yourself or you can ask on ports@ 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 to know which ports depend on the one you're updating? I created a small python script that use sqlports to find them, it's called "showvictims.py" for an obvious reasons and you can find it on the github repository I linked at the begining of this article.

Comparing Makefiles

grep is my friend. I mean if I see something particular, I won't try to be clever, I just search to see if the case already happens 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 put it at least in Cc). Wait for a commiter to pick it up. If after a week nothing moved, 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.