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 :
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):
and look for "offset". If there is some, you have to run
update-patches (and possibly edit the file getting patched). You
portsdiff to verify that there were no substitutions made that you will have to undo by hand.
Simulate the port installation
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:
For a python2-only port:
make REVISION=999 plist
For a python ports with a py3 flavor:
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
If there's something missing, one possible solution is to comment everything
portsldc again and copy the WANTLIB += lines.
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
the nm command from the FAQ, redirecting the output into
/tmp/before and doing the same
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.
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.
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.