Skip to content

Latest commit

 

History

History
212 lines (170 loc) · 9.9 KB

grep-0002-versioning.md

File metadata and controls

212 lines (170 loc) · 9.9 KB
Raw

GREP 0002 -- GNU Radio Versioning

History:

  • 01-Mar-2021: Initial Draft
  • 08-Jun-2021: Finalizing after reviews

Abstract

This document establishes the meaning of GNU Radio version numbers, and what kind of stability users can expect from a GNU Radio version. It extends the information in the VERSIONING file shipped within the GNU Radio repository.

GNU Radio uses a four-digit versioning scheme:

$MAJOR.$API.$ABI.$PATCH

The four digits have the following meaning:

  • $MAJOR: The major (or paradigm) version is only changed when major changes happen that affect the project as a whole. This number will be rarely changed, and a change would signal a massive change in the project. There is no guarantee whatsoever about compatibility between GNU Radio versions of different major version.
  • $API: The API version is changed whenever there are API changes in GNU Radio that would make external applications or out-of-tree modules incompatible with other API versions.
  • $ABI: The ABI versions is changed whenever the ABI changes in binary distributions of GNU Radio. Different versions with the same API version, but different ABI versions remain compatible, but it is possible that out-of-tree modules or other dependees of GNU Radio need to be recompiled or relinked.
  • $PATCH: This number is changed when changes to GNU Radio are made (typically bug fixes) that have no API or ABI impact. Different versions of GNU Radio that only differ in this number are fully compatible, and no changes in out-of-tree modules are required.

Copyright / License

This GREP is licensed as CC-BY-ND. Copyright 2021 The GNU Radio Project.

Motivation

GNU Radio version numbers should accurately convey a meaning. This document should be usable by any user of GNU Radio to get a good idea what they can expect from a GNU Radio version number in terms of compatibility.

Description

Major Version Number

Authors of out-of-tree modules and other third-party modules can expect the following from GNU Radio versions with the same major version:

  • The general design philosophy of GNU Radio remains the same
  • Out-of-tree modules may not be compatible, but there is an upgrade path

API Version Number

Authors of out-of-tree modules and other third-party modules can expect the following from GNU Radio versions with the same API version:

  • Neither Python nor C++ code needs to be modified.
    • Recompiling or re-linking might be necessary though.
  • The behaviour of the third-party code will be unchanged.
    • The exception to this is bug fixes in GNU Radio. In the extreme case where third-party code was deliberately using a bug in GNU Radio, the behaviour may change even within the same API version number.
  • GRC files should work without modification.
    • Python files generated by GRC may not work without re-generation from GRC.
  • Third-party dependencies of GNU Radio will not require an update.

The following non-comprehensive list contains actions that may be taken without increasing the API version:

  • Add API calls
  • Add in-tree components, although the maintainer may make the decision otherwise
  • Add optional arguments to existing API calls
  • Remove const keywords from methods for function arguments
  • Replace constexpr with const and vice versa

Historical examples

  • GNU Radio 3.8 changed the following things that required an increase in API version:
    • Dependency minimum versions were increased (e.g., Boost now requires version 1.65)
    • In-tree Modules gr-comedi, gr-fcd and gr-wxgui were removed. This would potentially require updates in OOT modules. Some blocks from gr-digital were removed, as were some PyQwt-dependent tools.
  • GNU Radio 3.9 changed the following things that required an increase in API version:
    • Dependency versions were increased (e.g., Boost now requires version 1.65)
    • SWIG was replaced by Pybind11, which requires modifications to OOTs.

ABI Version Number

Authors of out-of-tree modules and other third-party modules can expect the following from GNU Radio versions with the same ABI version:

  • Neither Python nor C++ code needs to be modified.
    • Neither Recompiling nor re-linking are necessary when updating GNU Radio.
  • The behaviour of the third-party code will be unchanged.
    • The exception to this is bug fixes in GNU Radio. In the extreme case where third-party code was deliberately using a bug in GNU Radio, the behaviour may change even within the same API version number.
  • GRC files should work without modification.
    • This includes Python files generated from GRC.
  • Third-party dependencies of GNU Radio will not require an update.

Retaining an ABI number typically requires special tooling (e.g., abidumper) to verify the stability of ABI.

Appendix

The following is a copy of GNU Radio's versioning formal definition.

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.

  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 text

The versioning scheme is based on SemVer 2.0.0; it's licensed under Creative Commons - CC BY 3.0