The maintainer's guide to Updating ports

Since OpenBSD 3.8, pkg_add can update packages. So maintainers have to be aware of one simple fact: update is not instantaneous. Even if a user just goes from release to release, each time they run pkg_add -ui, the system will replace each package with a new version, one package at a time. So the user will run a mixed system, even if it is for just a few minutes.

There are basically two update models of which maintainers must be aware.

• Some users follow current on a loose basis. They update their packages every few days/every few weeks. Either all packages, or only some selected packages. The update mechanism should work for them: it can force them to update some specific packages, or to install some new stuff, but it should not fail silently. Micro-updates must be tested. These users will most often be able to cope with small changes, like program name changes, or configuration adjustments.
• Some users update every six months with a new release. They also will download stable updates (security and critical updates). During six months, a large part of the ports tree changes. These users do not care about individual software changes. They just want a system that works. Changing binary names is completely unfriendly to these users. Tweaking hundreds of configuration files will be a major pain for them. Maintainers can help by providing smooth update paths, and major hints whenever something important changes.

You should note that part of the update process, especially the macroscopic changes for users who update every six months, is not yet automated. The global update mechanism is still a work in progress, and pkg_add will be able to cope with more issues in the future. As of now, you should focus on making sure the system updates correctly, one port at a time, and that one port's update takes other ports into account, as far as conflicts and other issues are concerned.

Naming packages and the update process

Conflicts, planning for the future

The icky business of renames and branches

Configuration files and update issues

Shared libraries issues

Update checklist

• Make sure the software authors are aware of your tweaks to make it run on OpenBSD. You must endeavor to get OpenBSD patches into the next release of the software. Otherwise, you can be prepared to rewrite most of your patches from scratch every release.
• Make sure the software authors understand version numbering. If the distfiles do not contain any version numbers, or if they reference current stuff, communicate with the authors so that you can get some permanent urls.
• Document work-arounds. This will help you remember to check whether they are still necessary when you try to update a port.
• Document dependencies. Especially the stuff you don't use. Some ports can use external software that may not be available at the time of porting. Make sure you do not pick it up, and document it, so that you can update your port when this software becomes available later.
• If the port uses libtool, copy its log verbatim as a basis for your SHARED_LIBS setup. This will help during updates.
• Use PLIST_DB and build a database of packing-lists. This is useful to find out about forgotten package name bumps, and also to check for conflicts with older packages.
• Make sure dependencies stay as loose as they can be. By default, RUN_ and LIB_DEPENDS will be satisfied by any version of a package. Do not insist on a given version unless you have to. Use minimal versions whenever possible.

• Each port update needs a package name bump. Otherwise, the update mechanism for binary packages won't work. Anything that affects the binary package implies a bump. This includes HOMEPAGE, MAINTAINER or description changes.
• If the package does not build, no bump is needed: changes to restore a port to working order after it got broken do not warrant bumps.
• Changes to make sure a port does not pick/does pick an external dependency warrant a bump.
• Changes in dependencies generally do not affect a port version number. The package system uses a signature mechanism such that a binary package is fully identified by its package names, plus the dependencies against which it was built, plus the version numbers of all shared libraries it contains.

• run make patch to have an initial copy of the port before the update.

• Edit the port's Makefile to grab the new version, run make makesum and make patch as a starting basis.
• Once you've fixed patches that failed, run a full diff between the old and the new version to figure out exactly what changed. Take notes, be prepared to revisit things later.
• Do whatever porting work is necessary to get the new version to run under OpenBSD, adjust dependencies, change package contents, etc.
• Double check shared library versions. For libtool-based ports, you have the shared_libs.log to check whether the software authors did significant changes. Note well that this is not enough. Most software authors do not really understand shared library issues. You have to read the full diff between the old and the new version, and bump library versions accordingly. When in doubt, bump the major version.
• Be aware of conflicts with already built packages. For simple updates, nothing needs to be done. If you split a package into several subpackages, make sure the subpackages have proper conflict annotations: they should usually conflict with the `old' single package.
• Help the user. If some specific steps must be taken beyond pkg_add -ui, make sure they are visible in the package. When your packaging policy changes, document it in the package description. For instance, if you move the documentation into a separate package for space constraints, the main package description should mention that the documentation is now available as a separate package.