diff options
| -rw-r--r-- | host/docs/uhd.dox | 1 | ||||
| -rw-r--r-- | host/docs/uhd_semvar.dox | 143 |
2 files changed, 144 insertions, 0 deletions
diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox index ea2b1ecee..5474d42e2 100644 --- a/host/docs/uhd.dox +++ b/host/docs/uhd.dox @@ -13,6 +13,7 @@ Some additional pages on developing UHD are also available here: \li \subpage page_converters \li \subpage page_stream \li \subpage page_rtp +\li \subpage page_semver \li \subpage page_rdtesting */ 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: |