OT/ICS Versioning 1.0.0

Summary

Given a version number MAJOR.MINOR.PATCH, increment MAJOR immediately before each formal acceptance test phase, MINOR for any functional change, and PATCH for backwards-compatible non-functional changes.

Introduction

Operational Technology (OT) and Industrial Control System (ICS) projects produce software across multiple device types - PLCs, HMIs, drives, instruments - developed iteratively through design, integration, and formal acceptance stages. A consistent versioning convention removes ambiguity throughout the project lifecycle, where precise identification of the software state is a safety and contractual requirement.

OTVer uses the MAJOR.MINOR.PATCH structure to express the events that matter in industrial automation: functional impact of changes and transitions between formal acceptance stages.

OT/ICS Versioning Specification (OTVer)

The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

  1. A version number MUST take the form X.Y.Z, where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the Major version, Y is the Minor version, and Z is the Patch version. Each element MUST increase numerically when incremented. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

  2. The Major version (X) MUST be incremented immediately before each formal acceptance test phase begins (e.g. Factory Acceptance Test, Site Integration Test, Site Acceptance Test). The software submitted for that acceptance test phase MUST carry the new version number. When the Major version is incremented, the Minor and Patch versions MUST be reset to 0.

  3. The Minor version (Y) MUST be incremented for any change with functional consequence, including: addition of new functionality, modification of existing functionality, and correction of a functional defect. When the Minor version is incremented, the Patch version MUST be reset to 0.

  4. The Patch version (Z) MUST be incremented for backwards-compatible changes with no functional consequence, including code refactoring, cosmetic changes to graphical interfaces, and corrections to documentation embedded in the software.

  5. The Patch component MAY be omitted for devices that do not have a programmable user interface and whose configuration is not subjected to refactoring. Such devices include, but are not limited to, variable-speed drives, soft starters, and field instruments (e.g. programmable sensors, signal transmitters, safety barriers). In such cases, the version SHALL take the form X.Y.

  6. When a project encompasses multiple devices, a project-level version MUST be maintained alongside the individual device versions. The project-level version MUST increment according to the most significant change across all devices included in a given release:

    • If any device in the release carries a Major increment, the project-level version MUST increment its Major.
    • If the most significant change across all devices is a Minor increment, the project-level version MUST increment its Minor.
    • If all changes are Patch-level, the project-level version MUST increment its Patch.

    The project-level version is not derived from any individual device version. At every acceptance test phase, all devices and the project-level version MUST be aligned to the same Major version.

See also: Device Type Codes and File Naming

Why OT/ICS Versioning?

Without a shared convention, version labels are ambiguous - a number alone does not indicate whether a change is functional, cosmetic, or tied to a formal acceptance milestone. OTVer gives version numbers a consistent meaning across teams, vendors, and project phases.

FAQ

Why not just use SemVer?

SemVer is designed around API compatibility: the Major version increments when a breaking change is introduced to a public interface. In OT/ICS projects there is no public API. The relevant versioning event is the transition between formal acceptance stages, which has no equivalent in SemVer. OTVer replaces the API compatibility model with one grounded in the industrial project lifecycle.

How do I handle hotfixes after SAT?

A change made after SAT is a post-acceptance modification. If the change has functional consequence, the Minor version MUST be incremented (e.g. 3.0.0 -> 3.1.0). If the change is backwards-compatible and non-functional, the Patch version MUST be incremented (e.g. 3.0.0 -> 3.0.1). If a new formal acceptance phase is defined for the change, the Major version MUST be incremented per item 2.

How does phase alignment work in practice?

Before FAT, devices may be at different versions (e.g. PLC v0.4.0, HMI v0.8.2). When FAT begins, all devices are aligned to v1.0.0. When SAT begins, all devices are aligned to v2.0.0. Individual version history before alignment does not matter.

What does project-level versioning look like?

Starting state: PRJ v0.1.0, PLC v0.3.0, HMI v0.8.2:

Release Change PRJ PLC HMI
1 PLC: functional changes v0.2.0 v0.4.0 v0.8.2
2 HMI: cosmetic changes only v0.2.1 v0.4.0 v0.8.3
3 FAT reached v1.0.0 v1.0.0 v1.0.0

What version do I start with?

Before the first formal acceptance test phase, the Major version MUST be 0 (e.g. 0.1.0). When the first acceptance phase begins, item 2 requires the Major version to increment to 1.0.0.

How does this relate to IEC 62443 or other standards?

Standards such as IEC 62443, IEC 61511, and IEC 61131 require software versions to be tracked and controlled but do not prescribe a version numbering format. OTVer fills this gap and does not conflict with any of these standards.

About

If you have feedback or suggestions, please open an issue on GitHub.

License

The OTVer Specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).