Search by Tags

Toradex Software Versioning Convention

 
Article updated at 13 Mar 2020
Compare with Revision


Subscribe for this article updates

Introduction

This page describes how software versioning is being done at Toradex.

Software Versioning Scheme

The new versioning aims to be fully Semantic Versioning compliant. This makes sure that version comparison is clearly specified and defined.

Release types

Pre-Releases

Represent development in progress. Tezi-Feeds: These images are not visible by default, need to be activated. Pre-Relases get the MAJOR.MINOR.PATCH triple of the next planned Major, Minor, or Patch release.

Nightly

Are done every night and are not guaranteed to work.

Monthly

Represent the current state of the development and the base features are tested by leveraging automated testing. Simply these are to be built at the first day of the month.

Releases

Are tested, representing the maturity of a developed product. Each release is denoted by a unique version number (main part). The main part of the version number has three different sub components: Major, Minor and Patch. Those sub components are incremented when one of the following three release types are built. Tezi-Feeds: Main feed, enabled by default and contains all the builds.

Major

Representing breaking changes and will be done once a year at the first quarter. This is the first release after the shift to a new OpenEmbedded branch.

[2].0.0

Minor

Representing updates, or changes that should not break backward compatibility (e.g. stay with the same OpenEmbedded release which usually means core components such as GCC and glibc stay at the same major version). Incrementing minor will typically be done three times a year (2nd, 3rd and 4th quarter).

2.[1].0

Patch

Patch releases are released on demand, typically to fix a security issue or to fix a broken functionality.

2.1.[1]

LTS Versions

Will represent a long-term supported versions. These will be the last Minor release every year. The target time range to support an LTS version will be 3 years starting from the release date. LTS won’t be part of the version number, we will just label that release as a LTS release.

Versioning concept

Image versions

We always use regular MAJOR.MINOR.PATCH versioning and follow largely Semantic Versioning. For our monthly and nightly development snapshots, we use devel as a pre-release identifier. Monthly development snapshots (every start of the month) will have a year & month date identifier added after devel.

2.0.0-devel-201909

Nightly development snapshots (every night before midnight) will have a year, month & day date identifier added after devel

2.0.0-devel-20190909

These two build types are directly built of the development branch and therefore only for testing purposes available for our customers. Because of this nature, the versioning is not intended to align with the other releases semantic versioning order.

Developer builds are always versioned as followed and will have a year, month, day & time date identifier added after devel:

2.0.0-devel-20190909193020

Master branch builds use the version number 0.0.0 to clearly state that those builds are not stable.

0.0.0-devel-20190909

Build number

To denote the build number we use the word build. The build number is added as build metadata (using the + sign) and is incremented on each complete OpenEmbedded build. The build number should also be available in the root file system (should be available in /etc/issue or /etc/os-release through the means of DISTRO_VERSION).

2.0.0-devel-201909+build.65
2.0.0-devel-20190909+build.122
0.0.0-devel-20190909+build.78

We also add the build number for the offical releases, e.g.

2.0.0+build.43

The Build number should allow to identify the build in the CI system.

Software Artifacts versioning

For software artifacts like Linux and U-Boot, we also added the Toradex Image version number to the localversion part of the software artifact version. For those artifacts, we only use the main version plus a denomination for pre-release (-devel) plus a git hash instead of the build number. This avoids unnecessary rebuilds and makes it easy to trace back the source code those pieces are built from, e.g.:

U-Boot: 2019.07-4.0.0-devel+git.03cac0835c
Linux: 5.3.10-4.0.0-devel+git.401bf3f29b1a

Example of a year of releases

Release date Release type Version number Comment
21 Dec 2020 Minor 4.3.0+build.201 LTS support
31 Mar 2020 Major 4.0.0+build.106 First build with new OE branch
02 Nov 2020 Monthly 4.3.0-devel-202011+build.815 Example if build failed on first
20 Jan 2020 Nightly 4.0.0-devel-20200120+build.315

Legacy

This versioning scheme was replaced by the Software Versioning Scheme. This document stays valid only for legacy releases and future WinCE releases.

Software Versioning

We make use of two different versioning schemes, a package version and an item version. The package version is the version showed in public, e.g. on websites, file names, roadmaps, etc. The item version gets built-in in e.g. drivers, libraries, kernels, or other items. The item version is usually visible when running the software or doing version queries only. Example: We build a BSP with item version 1.2.4. We call the download package 1.2b4 to indicate it's a beta version. If we declare this version stable, the item version stays at 1.2.4 but the package version will be changed to 1.2. This allows us to declare software stable after some time w/o rebuilding it just to update the item version.

Software Package Version

Usage

The package version is used to name downloadable packages or versions mentioned on websites, in Toradex Easy Installer, etc.

Format

Major.Minor[bx][.BuildNb][-nightly]-YYYYMMDD
Type Description
Major Mandatory major version number which changes if major changes were done. This includes major incompatibilities with earlier versions.
Can start at 0. Leading 0 are blanked (except for “0”).
.Minor Mandatory minor version number which changes after a stable release.
Can start at 0, Leading 0 are blanked (except for “0”).
bx Optional identifier. Used to identify beta releases. b is a constant letter and x is the ascending beta number starting from 1.
Leading 0 are blanked.
.BuildNb Optional Build Number to identify a specific build. E.g. used with automated CI builds.
Leading 0 are blanked. Can be any decimal number and doesn’t need to be monotonic. It’s just a build identifier number.
-nightly Optional identifier. Specifies builds which were automatically done overnight.
-YYYYMMDD Mandatory date identifier.

Examples

2.5b1-nightly-20170306
2.5b1.1536-nightly-20170306
2.5-20170307
2.5b1-20170301

Software Item Version

Usage

Item versions can be used for single items where the package version format doesn’t make sense, e.g. kernel, u-boot, drivers, etc. An item version can then be matched to a package version.

Format

Major.Minor[.Patch][-YYYYMMDD]
Type Description
Major Mandatory major version number which changes if major changes were done. This includes major incompatibilities with earlier versions.
Can start at 0. Leading 0 are blanked (except for “0”).
.Minor Mandatory minor version number which changes for sure after a stable release but also can change w/o stable release.
Can start at 0, Leading 0 are blanked (except for “0”).
.Patch Optional patch version number which changes during stabilizing a version. It can be a manually increased version number, or can also be a versioning system number, e.g. SVN revision number.
Starts with 1. Leading 0 are blanked.
-YYYYMMDD Optional date identifier.

Examples

2.5    
2.5.1
2.5.1-20170328
1.9.2394