USRP Hardware Driver and USRP Manual  Version: 3.11.0.HEAD-0-ge00f1f37
UHD and USRP Manual
UHD Semantic Versioning

Summary

Given a version number MAJOR.API.ABI.PATCH, increment the:

  1. MAJOR version as necessitated by product generation & architecture.
  2. API version when you make incompatible API changes,
  3. ABI version when you make incompatible ABI changes,
  4. PATCH version when you make backwards-compatible bug fixes.

Additional labels for other metadata may be appended to the version number as extensions.

Introduction

Version numbers play an important role in communicating the compatibility and restrictions of particular releases of software libraries. By defining formal semantics for the library versioning, users of the library can immediately and precisely comprehend the implications of updating that particular library in their application or system. This information is especially important to developers in environments where a very high degree of Reliability, Availability, Serviceability, and Manageability (1) are operational requirements.

Additionally, without strict versioning semantics, version numbers are effectively useless for dependency management. By adhering to a versioning specification, application developers can easily specify which existing & future versions of the library their software is compatible with. As a dependency, this makes the library easier to use, integrate, maintain, and plan around.

The Semantic Versioning (SemVer) specification was introduced in 2009 and is now a requirement of the Linux Foundation's Core Infrastructure Initiative's Best Practices Badge. The UHD Semantic Versioning (UHD-SemVer) specification is based on SemVer, but has been modified to better reflect the requirements of the Ettus Research user-space device driver workflow, project history, and application ecosystem.

UHD-SemVer Specification

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

  1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.
  2. A normal version number MUST take the form W.X.Y.Z where W, X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. W is the major version, X is the API version, Y is the ABI version, and Z is the patch version. Each element MUST increase numerically. For instance: 3.1.9.0 -> 3.1.10.0 -> 3.1.11.0.
  3. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
  4. Patch version Z (w.x.y.Z) MUST be incremented if only backwards API-compatible & ABI-compatible changes are introduced.
  5. ABI version Y (w.x.Y.z) MUST be incremented if changes break ABI compatibility with the previous release.
  6. API version X (w.X.y.z) MUST be incremented if changes break public API compatibility with the previous release. It MAY include ABI and patch level changes. It MAY be incremented if substantial new functionality or improvements are introduced within private code. ABI and PATCH version MUST be reset to 0 when API version is incremented. An API breakage is defined as the case where recompiling software against UHD without modifications may yield different results. The following cases, for example, are typically not API-breaking, but are ABI-breaking: adding new public methods, adding new default parameters to public methods if the default case is identical to the previous case.
  7. MAJOR version W (W.x.y.z) MAY be incremented if significant architectural or technological changes are made that warrant identifying the software as a new generation of product.
  8. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 3.1.0.0-alpha, 3.1.0.0-alpha.1, 3.1.0.0-0.3.7, 3.1.0.0-x.7.z.92.
  9. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 3.1.0.0-alpha+001, 3.1.0.0+20130313144700, 3.1.0.0-beta+exp.sha.5114f85.
  10. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into major, API, ABI, patch and pre-release identifiers in that order (Build metadata does not figure into precedence). Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, API, ABI, and patch versions are always compared numerically. Example: 3.1.0.0 < 3.2.0.0 < 3.2.1.0 < 3.2.1.1. When major, API, ABI, and patch are equal, a pre-release version has lower precedence than a normal version. Example: 3.1.0.0-alpha < 3.1.0.0. Precedence for two pre-release versions with the same major, API ABI, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 3.1.0.0-alpha < 3.1.0.0-alpha.1 < 3.1.0.0-alpha.beta < 3.1.0.0-beta < 4.1.0.0-beta.2 < 3.1.0.0-beta.11 < 3.1.0.0-rc.1 < 3.1.0.0.

License

Based on SemVer 2.0.0. Creative Commons - CC BY 3.0

1. For more information on enterprise RASM, see Wikipedia’s article on RAS and National Instrument’s whitepaper on RASM.