Merge branch 'maint'

1 files changed, 143 insertions, 0 deletions

diff --git a/host/docs/uhd_semvar.dox b/host/docs/uhd_semvar.dox
new file mode 100644
index 000000000..2a43b92f1
--- /dev/null
+++ b/host/docs/uhd_semvar.dox
@@ -0,0 +1,143 @@
+/*! \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: