forked from gnuradio/gnuradio
-
Notifications
You must be signed in to change notification settings - Fork 0
/
VERSIONING
132 lines (109 loc) · 6.55 KB
/
VERSIONING
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
# GNU Radio Versioning
For the 3.8 Release and going on, the following versioning scheme is to be used.
For 3.7 and earlier, other schemes apply.
GNU Radio versioning is based on [Semantic Versioning](https://semver.org).
## GNU Radio Versioning in 60s or less
If in doubt, the formal definition below applies. However, to ease use of this
versioning scheme, an abridged, specified conclusion is given in this section.
GNU Radio uses a four-number versioning:
```
A.B.C.D
```
* A is the paradigm version. This has been '3' for more than a decade, meaning:
> GNU Radio is a block-based flow graph framework that uses classes to represent
> blocks whose main feature is a `work()` function taking input samples from
> quasi-circular buffers and putting results in quasi-circular output buffers.
It's encouraged that in the future, relevant modifications and extensions of
that model will lead to changes to the paradigm version number.
* A.B is the public API version. We'll only accept patches that don't change the
public API on a `maint-A.B` branch. GNU Radio users need not change their code
to stay compatible with any future A.B.x.x version (barring bugs), but might
have to recompile.
Forward-going development should happen on the A.(B+1) branch, once A.B is
released.
* A.B.C is the ABI version. This includes C/C++, Python bindings and the
interfaces of GRC blocks. Programmers need not recompile their code if A.B.C
stays unchanged.
* A.B.C.D is the patch level. Versions A.B.C.D and A.B.C.D' are compatible with
one another, both binary and in API, although one versions might have fixed
bugs that the other has not.
### Formal Definition of GNU Radio's Semantic Versioning
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 GNU Radio 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 of this Document
The versioning scheme is based on [*SemVer 2.0.0*](http://semver.org/); it's
licensed under
[*Creative Commons - CC BY 3.0*](http://creativecommons.org/licenses/by/3.0/)