Proper library version numbering

[Ryan Schmidt]

We frequently find projects versioning their libraries incorrectly -- i.e., using the project's version number as the library version number. For example here's a library that I'm almost certain is doing it wrong:


$ port installed tidy
The following ports are currently installed:
  tidy @4.9.26_0+universal (active)

$ otool -L /opt/local/lib/libtidy.dylib
/opt/local/lib/libtidy.dylib:
	/opt/local/lib/libtidy.4.dylib (compatibility version 4.0.0, current version 4.9.26)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)


But it's not totally clear to me what proper library versioning entails -- what specifically I should be telling the developers of those projects to do instead. There are too many different version numbers. For example:


$ port installed gettext
The following ports are currently installed:
  gettext @0.19.4_0+universal (active)

$ otool -L /opt/local/lib/libintl.dylib 
/opt/local/lib/libintl.dylib:
	/opt/local/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.3.0)
	/opt/local/lib/libiconv.2.dylib (compatibility version 8.0.0, current version 8.1.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1151.16.0)


Assuming gettext is an example of proper library version numbering, what's the relationship between version "0.19.4" and version "8" and version "10.3.0"? What do each of those numbers represent? What would be the appropriate circumstances when a developer would change each of those numbers?