app: Add version file and releasing information

MarkusLassila · MarkusLassila · commit 170f4e586858 · 2026-05-25T13:15:56.000+03:00
- Added version file, which is used in application rollback
  prevention.

- Changed AT#XSMVER to use version file for SM.
  SM version in format:
  VERSION_MAJOR.VERSION_MINOR.PATCHLEVEL+VERSION_TWEAK

- Added information on how to modify version file and MCUboot
  monotonic counter for releases.

Signed-off-by: Markus Lassila &lt;markus.lassila@nordicsemi.no&gt;
diff --git a/app/CMakeLists.txt b/app/CMakeLists.txt
@@ -37,5 +37,3 @@ target_sources_ifdef(CONFIG_NRF_PROVISIONING app PRIVATE src/sm_at_provisioning.
 add_subdirectory_ifdef(CONFIG_SM_CARRIER src/lwm2m_carrier)
 
 zephyr_include_directories(src)
-
-include(cmake/sm_version.cmake)
diff --git a/app/VERSION b/app/VERSION
@@ -0,0 +1,5 @@
+VERSION_MAJOR = 1
+VERSION_MINOR = 99
+PATCHLEVEL = 0
+VERSION_TWEAK = 0
+EXTRAVERSION =
diff --git a/app/cmake/sm_version.cmake b/app/cmake/sm_version.cmake
diff --git a/app/cmake/write_sm_version_header.cmake b/app/cmake/write_sm_version_header.cmake
diff --git a/app/src/sm_at_commands.c b/app/src/sm_at_commands.c
@@ -29,7 +29,7 @@
 #include "sm_settings.h"
 #include "sm_at_host.h"
 #include "sm_at_fota.h"
-#include "sm_version.h"
+#include <zephyr/app_version.h>
 #include "sm_at_nrfcloud.h"
 #include "sm_log.h"
 
@@ -75,12 +75,12 @@ STATIC int handle_at_smver(enum at_parser_cmd_type cmd_type, struct at_parser *,
 
 	if (cmd_type == AT_PARSER_CMD_TYPE_SET) {
 		if (strlen(CONFIG_SM_CUSTOMER_VERSION) > 0) {
-			rsp_send("\r\n#XSMVER: %s,%s,\"%s\"\r\n",
-				 STRINGIFY(SM_VERSION), STRINGIFY(NCS_VERSION_STRING),
+			rsp_send("\r\n#XSMVER: \"%s\",\"%s\",\"%s\"\r\n",
+				 APP_VERSION_TWEAK_STRING, NCS_VERSION_STRING,
 				 CONFIG_SM_CUSTOMER_VERSION);
 		} else {
-			rsp_send("\r\n#XSMVER: %s,%s\r\n",
-				 STRINGIFY(SM_VERSION), STRINGIFY(NCS_VERSION_STRING));
+			rsp_send("\r\n#XSMVER: \"%s\",\"%s\"\r\n",
+				 APP_VERSION_TWEAK_STRING, NCS_VERSION_STRING);
 		}
 		ret = 0;
 	}
diff --git a/app/tests/.gitignore b/app/tests/.gitignore
@@ -0,0 +1,3 @@
+# Copied from app/VERSION at CMake configure (see cmake/use_app_version.cmake)
+at_commands/VERSION
+at_socket/VERSION
diff --git a/app/tests/at_commands/CMakeLists.txt b/app/tests/at_commands/CMakeLists.txt
@@ -4,23 +4,11 @@
 
 cmake_minimum_required(VERSION 3.20.0)
 
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/use_app_version.cmake)
+
 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
 project(at_commands)
 
-# Generate sm_version.h header
-set(GENERATED_DIR "${PROJECT_BINARY_DIR}/generated")
-file(MAKE_DIRECTORY "${GENERATED_DIR}")
-add_custom_target(
-    generate_version_header ALL
-    COMMAND ${CMAKE_COMMAND}
-            -D OUTPUT_FILE=${GENERATED_DIR}/sm_version.h
-            -P ${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/write_sm_version_header.cmake
-    BYPRODUCTS ${GENERATED_DIR}/sm_version.h
-    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../..
-    COMMENT "Regenerating sm_version.h"
-)
-zephyr_include_directories("${GENERATED_DIR}")
-
 # Compiler options to set configuration values
 target_compile_options(app PRIVATE
   -DCONFIG_NRF_MODEM_LIB_MEM_DIAG=y
diff --git a/app/tests/at_socket/CMakeLists.txt b/app/tests/at_socket/CMakeLists.txt
@@ -6,23 +6,11 @@
 
 cmake_minimum_required(VERSION 3.20.0)
 
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/use_app_version.cmake)
+
 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
 project(at_socket_test)
 
-# Generate sm_version.h header
-set(GENERATED_DIR "${PROJECT_BINARY_DIR}/generated")
-file(MAKE_DIRECTORY "${GENERATED_DIR}")
-add_custom_target(
-    generate_version_header ALL
-    COMMAND ${CMAKE_COMMAND}
-            -D OUTPUT_FILE=${GENERATED_DIR}/sm_version.h
-            -P ${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/write_sm_version_header.cmake
-    BYPRODUCTS ${GENERATED_DIR}/sm_version.h
-    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../..
-    COMMENT "Regenerating sm_version.h"
-)
-zephyr_include_directories("${GENERATED_DIR}")
-
 # Compiler options to set configuration values
 target_compile_options(app PRIVATE
   -DCONFIG_NRF_MODEM_LIB_MEM_DIAG=y
diff --git a/app/tests/cmake/use_app_version.cmake b/app/tests/cmake/use_app_version.cmake
@@ -0,0 +1,16 @@
+#
+# Copyright (c) 2026 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+# Keep app/VERSION as the single source of truth while leaving
+# APPLICATION_SOURCE_DIR on the unit-test project (own prj.conf, Kconfig, CMock).
+
+set(SM_APP_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)
+
+if(NOT EXISTS "${SM_APP_SOURCE_DIR}/VERSION")
+  message(FATAL_ERROR "Serial Modem VERSION file not found: ${SM_APP_SOURCE_DIR}/VERSION")
+endif()
+
+file(COPY "${SM_APP_SOURCE_DIR}/VERSION" DESTINATION "${CMAKE_CURRENT_SOURCE_DIR}")
diff --git a/doc/app/README.rst b/doc/app/README.rst
@@ -70,6 +70,7 @@ See the subpages for how to use the application, how to extend it, and informati
    sm_build_and_run
    sm_logging
    sm_configuration
+   sm_releasing
    sm_cellular_modem
    sm_data_mode
    sm_extending
diff --git a/doc/app/at_generic.rst b/doc/app/at_generic.rst
@@ -155,6 +155,8 @@ Test command
 
 The test command is not supported.
 
+.. _SM_AT_XSMVER:
+
 |SM| version #XSMVER
 =====================
 
@@ -177,9 +179,11 @@ Response syntax
 
 ::
 
-   #XSMVER: <sm_version>,<ncs_version>[,<customer_version>]
+   #XSMVER: "<sm_version>","<ncs_version>"[,"<customer_version>"]
 
 The ``<sm_version>`` parameter is the version of the |SM| application.
+It comes from :file:`app/VERSION` (``APP_VERSION_TWEAK_STRING``) and matches the MCUboot sign version.
+See :ref:`sm_releasing` for release version updates.
 
 The ``<ncs_version>`` parameter is a string containing the version of the |NCS|.
 
@@ -192,19 +196,24 @@ The following command example reads the versions:
 
 ::
 
-   // Released build
+   // First shipped 2.0 pre-release
+   AT#XSMVER
+   #XSMVER: "1.99.0+1","3.3.99"
+   OK
+
+   // Next shipped pre-release
    AT#XSMVER
-   #XSMVER: "v0.1.0","3.1.99"
+   #XSMVER: "1.99.0+2","3.3.99"
    OK
 
-   // Development build
+   // 2.0.0 release
    AT#XSMVER
-   #XSMVER: "v0.1.0-73-g0c2af8c-dirty","3.1.99"
+   #XSMVER: "2.0.0+0","3.4.0"
    OK
 
-   // Released build with customer version
+   // Shipped pre-release with customer version
    AT#XSMVER
-   #XSMVER: "v0.1.0","3.1.99","Onomondo 2.1.0"
+   #XSMVER: "1.99.0+2","3.1.99","Onomondo 2.1.0"
    OK
 
 Read command
diff --git a/doc/app/sm_releasing.rst b/doc/app/sm_releasing.rst
@@ -0,0 +1,58 @@
+.. _sm_releasing:
+
+Releasing |SM|
+##############
+
+Before each official release or pre-release, update the version metadata below.
+Each published image must carry a higher value than the previous one on the same line (application sign version or MCUboot ``fw_info.version``).
+
+Application — :file:`app/VERSION`
+=================================
+
+Sets ``AT#XSMVER`` and the MCUboot application sign version (``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION``), which is used for application downgrade prevention.
+Format: ``major.minor.patchlevel+VERSION_TWEAK``. See `Zephyr application VERSION <zephyr:app-version-details>`_.
+
+Pre-releases
+------------
+
+Before General Availability (GA): fix ``VERSION_MAJOR``, ``VERSION_MINOR``, and ``PATCHLEVEL`` on the pre-GA line; increment ``VERSION_TWEAK`` per published build.
+Example for 2.0.0 GA — line ``1.99.0``, images ``1.99.0+1``, ``1.99.0+2``, …
+
+.. code-block:: none
+
+   VERSION_MAJOR = 1
+   VERSION_MINOR = 99
+   PATCHLEVEL = 0
+   VERSION_TWEAK = 1
+
+General Availability (GA)
+-------------------------
+
+Set the product version and ``VERSION_TWEAK = 0``.
+
+.. code-block:: none
+
+   VERSION_MAJOR = 2
+   VERSION_MINOR = 0
+   PATCHLEVEL = 0
+   VERSION_TWEAK = 0
+
+``2.0.0+0`` must be greater than every shipped ``1.99.0+N`` pre-release.
+
+After GA: increment ``PATCHLEVEL`` or ``VERSION_TWEAK`` for each new published application build on that line.
+
+Do not bump ``VERSION_TWEAK`` for unpublished local or CI builds.
+Record Git tag ↔ ``+`` value in release notes.
+Confirm the version with :ref:`SM_AT_XSMVER`.
+
+MCUboot — ``CONFIG_FW_INFO_FIRMWARE_VERSION``
+=============================================
+
+:file:`app/sysbuild/mcuboot/prj.conf`
+
+Increment only when the MCUboot bootloader image changes.
+Used by NSIB (B0) for MCUboot slot downgrade prevention — independent of :file:`app/VERSION`.
+
+After an MCUboot update, ``AT#XBOOTINFO=0`` reports the active slot value.
+
+See :ref:`serial_modem_release_notes`.
diff --git a/doc/app/sm_testing.rst b/doc/app/sm_testing.rst
@@ -26,7 +26,7 @@ Complete the following steps to test the functionality provided by the :ref:`SM_
       :class: highlight
 
       **AT#XSMVER**
-      #XSMVER: "v0.1.0","3.1.99"
+      #XSMVER: "1.99.0+0","3.1.99"
       OK
 
 #. Retrieve a list of all supported proprietary AT commands.
diff --git a/doc/releases/migration_notes_v2.0.0.rst b/doc/releases/migration_notes_v2.0.0.rst
@@ -28,6 +28,10 @@ Informational changes
 
 The following changes are listed for informational purposes, and many hosts will work without any changes.
 
+* ``AT#XSMVER`` response format — In v1.x.x, the first field was a Git describe string (for example ``"v1.0.0"`` or ``"v1.0.0-3-g1a2b3c4"``).
+  From v2.0.0, it is the numeric version from :file:`app/VERSION` in the form ``"major.minor.patch+tweak"`` (for example ``"2.0.0+0"``).
+  It is aligned with the MCUboot application sign version which is used for application rollback prevention.
+
 * Ring Indication (RI) - Change RI from pulse (100 ms) to level triggered, meaning RI stays asserted until the host asserts DTR.
   After the Serial Modem has enabled UART, RI will be deasserted.
 * nRF Cloud transport has been changed from MQTT to CoAP.
diff --git a/doc/releases/releases.rst b/doc/releases/releases.rst
@@ -5,6 +5,8 @@ Release notes
 
 For all the notable changes to the |SM|, see the `releases on GitHub <github_release_>`_.
 
+When preparing a release or pre-release build, see :ref:`sm_releasing`.
+
 .. toctree::
    :maxdepth: 2
    :caption: Subpages:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Copied from app/VERSION at CMake configure (see cmake/use_app_version.cmake)`
	`2`	`+at_commands/VERSION`
	`3`	`+at_socket/VERSION`