1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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:
|
