# 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/)