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.PATCH in the top level Changelog.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.

Note: If this is the first commit after a release, make sure to increment the patch number 1) in the CMakeLists and 2) a new entry in the changelog.

The master branch

The master branch contains new features and many times is subject to API and ABI changes. In general, the master branch should compile, though its possible that with new features come new bugs.

Feature branches: When maintaining master, minor features and fixes for recent additions can go in at any time, but major features should be merged from a feature branch. Developing features on master could be disruptive to users. Its recommended to complete features on a dedicated "feature" branch and then to merge it into master when ready.

Maintain the changelog: The master branch is a new major release in progress, and the changelog entry should contain brief descriptions. The entries should be pertinent to the next major release. For example: There's no need to mention fixes that only affect unreleased features. Pertinent entries might be:

• API changes/breakages
• major features/additions
• removal/deprecations

Note: If this is the first commit after a release, make sure to set a new version number 1) in the CMakeLists and 2) a new entry in the changelog. If this is the first API or ABI change after a release, also modify the relevant numbers in the CMakeLists/includes mentioned above.

Note2: And make sure that the images are available for the latest release. These major.minor numbers are used to format the URL so images can be versioned with the software: http://downloads.myriadrf.org/project/limesuite/

Debian packaging

The project contains a debian/ directory for building debian source packages which can be used to upload to PPA among other things.

Building locally

Use the git build package tool to create a set of debs or to test the build:

gbp buildpackage --git-ignore-new --git-ignore-branch --git-export=WC --git-upstream-tree=HEAD --git-export-dir=$HOME/build-area

Uploading to a PPA

Uploading a source package to the PPA involves

1. customizing the changelog with email and OS release,
2. running git build package to get a source package,
3. uploading the source package to the ppa with dput.

I've created a helper script to automate the process. Feel free to pick it apart or change it.

#this is an email registered with the PPA, pass it in with environment variables
export DEBFULLNAME="YOUR NAME"
export DEBEMAIL="YOUR-EMAIL@gmail.com"

#run the PPA helper, specify the OS release (xenial)
#The branch option will automatically used the latest release on that branch or
#make a special version that is the latest release + number of commits since
ppa_helper --source=/path/to/LimeSuite --branch=stable --series=xenial --suffix=myriadrf1 --upload=ppa:myriadrf/drivers

Maintaining debian/

The debian/ directory contains a few files that mirror the version numbers found in the Changelog.txt. When making a new release the process is:

• control - find and replace the version numbers for the current major release
• changelog - add a new entry for every major/minor and patch release
• liblimesuite[version]-1.install - rename to match current library ABI

Making a release

Making a release is a checklist of tasks to get all of the numbers right and to create a git tag:

Update numbers and dates

Is this a patch release?

git checkout stable

Is this a major/minor release?

git checkout stable
git pull origin master #master becomes the new stable

1. Edit Changelog.txt, but the current date of the release and double check the version number
2. Major release or ABI changes? update src/VersionInfo.h and debian/control and liblimesuite[version]-1.install files
3. Make a new entry in debian/changelog to match
4. Finally commit the changes and push to stable

Make the git tag

After making the commit, make the tag to match the current version Follow this format:

git tag -a v17.03.0 -m "Lime Suite v17.03.0"
git push origin v17.03.0 #make it public

Update master

Always update the master branch to include the latest release information. No matter if this is a patch or major/minor release:

git checkout master
git pull . stable
git push origin master #resolve any conflicts