ReleaseGuide

The release guide is a helpful page intended to manage the creation of releases for the LimeSuite project, although its notes should be applicable to other projects.

Version numbers

The LimeSuite library has several similar version numbers to indicate project releases and other kinds of library compatibility. Mind them carefully. Here is a quick summary of these numbers and how they come into play. We will describe in more detail how to handle these numbers for making full and patch releases.

Project version number

The project has a 3 digit version number in the form of year.month.patch.

• The first digit is the current year as a two digit number (16, 17....)
• The second digit is the current month as a two digit number (01, 02, 03, 04..11, 12)
• The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)

• The project version number is set by modifying VERSION_MAJOR, MINOR, and PATCH in the top level CMakeLists.txt

API version number

The API version number is very similar to the project version number and it is primarily used for clients of the library to be able to detect API differences using preprocessor defines. For example if the project version number is 17.03.*, the library API will be defined as #define LIME_SUITE_API_VERSION 0x20170300. A client application can use preprocessor macros and simple hex shifts to detect the API version.

Typically, the API version will not change during a major.minor release cycle. However, consider the following example: Suppose that the 17.03.1 release had an important fix, and by consequence modified how a particular API call operates under some conditions. To enable a client application to detect this change, we might modify the API accordingly #define LIME_SUITE_API_VERSION 0x20170301. The last two digits don't have to match the patch number, they just need to be modified so that a client can detect that change in a meaningful way. The usefulness of this this technique simply comes down to the specific circumstances. For example, a client application might have to maintain compatibility both for the current release and the yet-to-be-released stable branch that contains the API change.

• The API version is set by editing LIME_SUITE_API_VERSION in src/VersionInfo.h

ABI version number

The ABI version number represents the binary format of the library. The exact combination of functions, arguments, and classes form the ABI of the library. Typically, modifications of the headers of a library will cause ABI changes. If the ABI of the library is changed, its client applications must be recompiled or they will experience unknown failures like segmentation faults. On a unix system, the ABI is expressed as a suffix on the library. This allows multiple versions of the library to co-exist on one system.

Although the ABI number is actually arbitrary, it should be used to represent the ABI of a version release, and changed when the ABI of the library actually changes. In LimeSuite the ABI is set to major.minor-1 by default. The only reason to change this, is if the ABI is broken for a patch release. This should be avoided in most cases.

• The ABI version number can be modified by editing LIME_SUITE_SOVER in the top level CMakeLists.txt

Example unix library layout

Here is a demonstration for how these various version numbers come into play on a typical unix system

ls -al /usr/lib/libLimeSuite*

libLimeSuite.so -> libLimeSuite.so.17.03-1
libLimeSuite.so.17.03-1 -> libLimeSuite.so.17.03.0
libLimeSuite.so.17.03.0

• libLimeSuite.so is a symlink to the current library, its used for development purposes as a conveniently named file to link against
• libLimeSuite.so.17.03-1 is named after the ABI, other packaged applications look for this library by name. It symlinks to the latest installed version
• libLimeSuite.so.17.03.0 is the actual library file and is named after the currently installed version of the library package

Git branching

The LimeSuite repository has two important branches: stable and master.

• The stable branch represents the latest release plus again additional fixes.
• The master branch is is where new features and API/ABI changes occur.

The stable branch

The stable branch gives users a way to track the most recent release plus any new fixes. Patch releases will be tagged from the stable branch.

Here is the procedure for maintaining stable:

• First a bug or typo is found. The fix should be applied to the stable branch (not master).
• Edit the Changelog.txt with a brief description of the change. This makes it obvious what fixes have been addressed since the last release.
• Push the commit(s) for the change and the Changelog to the stable branch.
• Not its time to update the master branch. Merge stable into master and resolve any conflicts.