uhd/host/docs/uhd_semvar.dox

/*! \page page_semver UHD Semantic Versioning

\section semver_summary 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``.

\section semver_intro 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 (\ref footnote_rasm "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*](http://semver.org/) (SemVer) specification
was introduced in 2009 and is now a requirement of the Linux
Foundation's
[*Core Infrastructure Initiative's*](https://www.coreinfrastructure.org/)
[*Best Practices Badge*](https://www.coreinfrastructure.org/programs/badge-program).
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.

\section semver_spec 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*](http://tools.ietf.org/html/rfc2119).

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.

\section semver_license License

Based on [*SemVer 2.0.0*](http://semver.org/).
[*Creative Commons - CC BY 3.0*](http://creativecommons.org/licenses/by/3.0/)

\anchor footnote_rasm 1. For more information on enterprise RASM, see
[*Wikipedia’s article on RAS*](https://en.wikipedia.org/wiki/Reliability,_availability_and_serviceability_(computing))
and [*National Instrument’s whitepaper*](http://www.ni.com/white-paper/14410/en/)
[*on RASM*](http://www.ni.com/white-paper/14410/en/).

*/
// vim:ft=doxygen: