Skip to content

Semantic App Versioning

How it works

Semantic app versioning is a scheme for determining how to assign a new version number to software to based on the difference between the previous version and the new version. With a clear defined versioning, it helps developer and end-user to avoid version lock as well as dependency hell.

In general you need at least 3 version numbers as integers to make the versioning works, which are MAJOR.MINOR.PATCH.

PATCH

Let's start with PATCH, it is defined as internal fix of the software. As an example, whenever you improves the performance or fixes a bug from your published software, you should update the PATCH number.

The goal of the PATCH is that end-user can upgrade or downgrade the software without problem. And it is recommended to update the software without hesitation.

MINOR

The MINOR version number means the changes made in the application is fully backward compatibility. When you add new feature or mark an API function as deprecated in future version. PATCH version number must be reset to 0 when MINOR version is incremented.

The goal of the MINOR is to tell end-user that you have updated new features and small changes are made, but nothing will break after updating the application to this newest version. End-user can downgrade the MINOR version in any time.

MAJOR

The MAJOR version number gives the warning sign to the end-user. It indicates that updates are incompatible. Most of the time the MAJOR version is incremented whenever you remove an API endpoint or change API endpoint name to modify the software infrastructure. PATCH and MINOR version numbers must be reset to 0 when MAJOR version is incremented

The goal of the MAJOR is to warn end-user not update this version of software easily. And after update, end-user needs to test the existing system extensively and eventually changes the code which is depending on the old already removed functionality.

Reference Semantic App Versioning

For more information about Semantic App Versioning see https://semver.org/ and an illustrated guide

Best Practice for Industrial Edge App

In addition to use the MAJOR.MINOR.PATCH template, this guide also provides a best practice to backtrack your own edge application easily.

We define 3 additional version stages Release, Release Candidate and Development with commit-number directly after MAJOR.MINOR.PATCH. In general it will look like MAJOR.MINOR.PATCH-STAGE.COMMIT. Where STAGE is written as 0.dev for development stage or 1.rc for release candidate stage or 2.r for release stage. To understand better how it works, let's consider you are developing your edge software, and currently you are on version 1.0.0

  • Development stage: In the development stage, after you commit your latest change from the repository. Consider your commit number is b9c12ff5. You can mark your software version as 1.0.0-0.dev.b9c12ff5 on Edge App Publisher, upload your software onto IEM and install on your IED.
  • Release candidate stage: After you tested your software extensively on your dedicated Edge Device, and everything seems working. You can now copy and mark your software as 1.0.0-1.rc.b9c12ff5 on Edge App Publisher. Indicating that it is a release candidate version with potential to be a stable product.
  • Release stage: After going through all the PLM (Product Lifecycle Management) processes and passed all verification tests, the software is considered to be stable and is ready to be released. You can now copy and mark the software version as 1.0.0-2.r.001 on Edge App Publisher.

NOTICE

The maximum version number length in Edge App Publisher is 32 characters.
The "Major", "Minor" & "Patch" version numbers are restricted to max safe integer value (9007199254740991).
The "Metadata" version number value is restricted to 16 characters, and it must start with '+' or '-' only.

Example for Semantic App Versioning

Now you have 3 versions of the same software on your IEM. The precedence of these 3 versions are compared numerically with the same MAJOR.MINOR.PATCH. They are showed as following under the IEM UI from top to bottom: 1.0.0-2.r.001 > 1.0.0-1.rc.b9c12ff5 > 1.0.0-0.dev.b9c12ff5