# Firmware Versioning ## Contents * [Introduction](#intro) * [Version Types](#ver-types) * [Release Versioning](#rel-ver) * [Build Versioning](#build-ver) * [Version Header](#ver-header) * [Version Tool](#ver-tool)

## Introduction Firmware versioning has two main types `release versioning` and `build versioning`. With each release a release version will be updated manually in the file `/src/comps/fw-version/fw_version.h` and a git tag will be created with the release version. Each firmware build will have a build version with more customizable identities as will be explained later.

## Version Types

### Release Versioning Release version follows the following format: ``` v.. Examples: v1.0.0 , v3.3.12 ``` Release versioning comprises the following components: * `` with reflects incompatible changes in the APIs and new features. * `` with reflects changes with backward compatibility. * `` with reflects backward compatible bug fix.

### Build Versioning Build version follows the following format: ``` ---[-] Examples: v1.0.1-23-d33c144-20240326-hotfix v1.12.1-89-2f36de5-20240209 v1.3.2-6-c212d9e-20240313-dirty ``` Build versioning comprises the following components: * `` the latest release git tag prior or equals to the current build git tag. and its format is same as the release-version.. * `` the number of git commits since the `` till the current build ``. * `` the current abbreviated git hash value. * `` the current date in this format `YYYYMMDD`. * `` a provided custom string to be appended to the build version. If the current firmware git hash has modification, and no provided custom string, the word dirty will be used instead.
The custom string can be passed to the build system `builder.py` tools using the option `--custom-version-string`

## Version Header The file `/src/comps/fw-version/fw_version.h` is the main firmware version header file that can be used anywhere in the firmware to use the firmware versioning variables and methods. The current firmware release version is statically and manually updated in this file. The following variables carries the release versioning information. |variable|description| |:--|:----| |FW_RELEASE_VERSION_MAJOR| firmware release major number| |FW_RELEASE_VERSION_MINOR| firmware release minor number| |FW_RELEASE_VERSION_PATCH| firmware release patch number| |FW_RELEASE_VERSION_STRING| release version string in its dedicated format| The build system generates the build versioning components and pass it to the source code during compilation in the variable `FW_GENERATED_BUILD_VERSION_HEADER`.
This generated file defines the following variables: |variable|description| |:--|:----| |FW_BUILD_VERSION_ENABLE|identifies if the build versioning components are present or not| |FW_BUILD_VERSION_GIT_TAG|the `` component as a string| |FW_BUILD_VERSION_GIT_DELTA|the `` component as a string| |FW_BUILD_VERSION_GIT_HASH|the `` component as a string| |FW_BUILD_VERSION_DATE|the `` component as a string| |FW_BUILD_VERSION_CUSTOM|the `` component as a string or `"None" value` if not present| |FW_BUILD_VERSION_STRING|the complete build version string| > **Remark**: the variable `FW_VERSION_STRING` selects the build version if it is > applicable and present, otherwise it will select the release version string. > this variable can be used eventually irrespective of the version type.

## Version Tool A versioning tool exists to organize and help other parties such as the build system to utilize the firmware versioning. The version tool exists at the path `/src/comps/fw-version/fw_version.py`. Issue this command to navigate its help screen: `/src/comps/fw-version/fw_version.py --help` The displayed help screen is like this ![FW-Version Tool Help Screen](fw-version-help.png) The build system uses it to deduce the needed version string type or to generate the intended generated build version header file. ```shell # Examples # get the release version python3 src/comps/fw-version/fw_version.py release-version # output may be:: v1.0.0 # get the build version python3 src/comps/fw-version/fw_version.py build-version # output may be:: v4.4.4-433-3cec3a0026-20240321 python3 src/comps/fw-version/fw_version.py build-version \ --custom-string "lib-x fix" # output may be:: v4.4.4-433-3cec3a0026-20240321-lib-x_fix python3 src/comps/fw-version/fw_version.py \ generate-header \ --custom-string "lib-x fix" \ --header-file path/to/generated_build_version_header.h # output may be:: v4.4.4-433-3cec3a0026-20240321-lib-x_fix ```