PSA: Handling library updates

[coypu%sdf.org@localhost]

Hi tech-pkg,

We've had some cases of library updates that went wrong. These are
mostly visible to binary package users:
http://gnats.netbsd.org/52507
https://twitter.com/kapper1224/status/909682115276562434

We could use a more reliable system, but while this one exists, it will
be good to remind how to do library updates.

Cases to bump minimum version required in buildlink3.mk and do a
recursive revbump:

- Dynamic linking major update (*.so library)

	libicu18n.so.58.2 -> libicu18n.so.59.1
	readelf to dependent users says:
	(NEEDED) Shared library: [libicu18n.so.58]

	Note: a change libicu18n.so.58.1 -> libicu18n.so.58.2 doesn't
	require the same, assuming upstream is responsible.[1]

- Directory path includes version:

	PREFIX/lib/perl5/5.26.0/...
	Anything using this path will need to be updated or fail to run.


In both these cases, all dependent users of the package must be updated,
and must never use the old version. To guarantee this, we do:

- Update minimum version in buildlink3.mk
BUILDLINK_ABI_DEPENDS.icu+=     icu>=59.1nb1

- bump PKGREVISION in all dependent users:
	- Obtain pkgtools/revbump
	- Follow step by step instructions in 'man revbump', which currently are:

           cd /usr/pkgsrc ;
           finddepends category/package | sort -u > allbump ;
           grep buildlink3.mk allbump | sed 's/.buildlink3.mk//' > bl3bump ;
           grep -e Makefile.common -e mk$ allbump | grep -v -e buildlink3.mk -e options.mk > commonbump ;
           replace-commonbump ;
           cat allbump commonbump.replaced | sed 's,/[^/]*$,,' | sort -u > makebump ;
           revbump < makebump | tee makebump.manual ;
           # [if a package is listed in makebump.manual, handle the PKGREVISION bump manually]
           blbump < bl3bump | tee bl3bump.manual ;
           # [handle the *ABI_DEPENDS* bumps in bl3bump.manual manually, usually none] ;
           cvs diff -u `cat makebump` > cvs-diff ;
           check-cvs-diff  ;
           cvs diff `cat bl3bump makebump` | less
           cvs commit `cat bl3bump makebump`
           rm allbump bl3bump* makebump* commonbump* cvs-diff

	This means the package will now say 'I need ICU 59', and will be
	rebuilt.


Cases to only bump PKGREVISION, without adjusting buildlink3.mk:

- Static linking (e.g. Golang update, *.a library)

	In this case, the library is embedded within the package. A new
	version of the library is a change to the package, so we bump
	PKGREVISION (with pkgtools/revbump).


In short: pay attention to PREFIX/lib changes and to programming
language updates.


[1] An example past case was OpenSSL changing default config options,
removing functions. This also breaks binary compatibility, and requires
bumping the minimum version and a recursive revbump.