The Communications of the ACM published an article called “Version Aversion”, which discusses various approaches to using version numbers in a software project. Much of the discussion mirrors the content in my book, API Design for C++, including the use of major/minor/patch version triples, tips on when to bump each of these version numbers, and reference to more esoteric versioning schemes like the Windows operating system choice of Windows 95, Windows 98, Windows ME, Windows NT, Windows XP, etc. You’ll need access to the ACM Digital Library to read the article.

• http://portal.acm.org/citation.cfm?id=1831407.1831420

Garrett Rooney wrote an article called “Preserving Backward Compatibility” where he talked about how backward and forward compatibility is maintained for Subversion,  client/server source control management (SCM) system. Garrett talks about the importance of planning ahead, not throwing anything away, and of hiding the details. He also talks about exposing and hiding the dependencies of your API. This is a great article to read about how backward compatibility is maintained in a complex real-world system.

• http://onlamp.com/pub/a/onlamp/2005/02/17/backwardscompatibility.html?page=2

The Symbian Developer wiki defines a process for public API changes to the Symbian platform. This involves a submitting a Change Request (CR) to an Architecture Council for approval before code is integrated. The main principles of their API development process are:

• Public APIs must remain backwards compatible during their lifetime.
• Public APIs can be extended with non-disruptive changes.
• Public APIs must go through a deprecation period before removal.

For details, see:

• http://developer.symbian.org/wiki/index.php/Public_API_Change_Control_Process

The API process is illustrated with the following figure:

The KDE Project offers some guidance on the difference between source and binary compatibility, and provides a great list of Do’s and Don’ts if you want to maintain binary compatibility for an API.

• http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++

This document defines binary and source compatibility as:

A library is binary compatible, if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn’t require any further modifications, the library is source compatible.