Page History

...

This policy was updated with TSC approval on 6/1925/19.

Release Cycle / Cadence

...

EdgeX's versioning scheme is based on semantic versioning (https://semver.org/).  However, the project may, at times, decide to release a major version due to significance-based changes or marketing decision.  

The EdgeX codenamed release should not be confused with MAJOR version!  Per semantic versioning definition, a MAJOR version is typically a significant milestone in the product that includes key features or updates and may include non-backward compatible changes (features, APIs, etc).  Not all of the EdgeX codenamed releases completed each six months will be “significant” or contain “non-backward compatible changes”. See major, minor and patch version information below.

Independent Tools and Services Release Cycle/Cadence

Some EdgeX services (and tooling) have a separate release cycle.  The Device Service SDKs, Device Services, Application Services and Application Functions SDK, for example, are not necessarily released with the EdgeX release.  Which services are allowed to have their own release cycles is at the discretion of the EdgeX Technical Steering Committee (TSC).  Services or tools that have their own release cycle may choose to release at the same time as the EdgeX release (the code named release) but are not required to and the version of these services or tools may not be the same as the versions of the services and tools associated to the EdgeX release.  Today, the following tools and services are released on independent release cycles:

• Device Service SDKs (Go and C)

• Device Services

• Application Functions SDK (Go)

• Application Services

When appropriate, a working group chairperson requests permission to release these tools and services.  The release manager, at the request of the working group chairperson, are responsible for the release of these tools and services.  Again these independent tools and services are versioned by semantic versioning to indicate what is included with the release (and specifically whether it includes compatible or non-compatible features and APIs).  Disagreements with a release manager decision about when to release is adjudicated by the TSC.

While the release cycle for these independent services varies from the EdgeX release, the rules on major, minor, and patch releases and versioning (as discussed below) still apply.   As an example, the SDK decides to release 1.0 with Edinburgh. There are no other changes to the SDK for two years. SDK remains 1.0 during that period. After 2 years, when EdgeX “Indiana” is released at version 5.0, the SDK decides to also make a minor version release.  They release 1.1 under semantic versioning rules (backward compatible, etc). The SDK (and DS) are separate from EdgeX release and therefore the versions may not coincide. They can elect to release and version at the same time as EdgeX release, but they are not part of EdgeX release by definition.

Version Query

All services will have a “ping” API that will respond with the version number.  This allows independent services and tooling (listed in the previous section) to query other EdgeX services that it works with and check for compatibility.  For example, when a Device Service built to work with EdgeX 1.0 comes up and it queries Core Data via the ping API and gets a response of 2.0, the device service can choose to log the issue (providing a clear indication of a version mistach) and exit.  The query calling service determines whether it is compatible or not (exiting or continuing). Each services only offers a query API that indicates what version of EdgeX it is.

Major, Minor Versions

...

, Patches and Pre-release Versions

Again, EdgeX follows semantic versioning.  Major Major releases have a “major number” or version number like 1.0, 2.0, etc.  Major Major releases will typically include significant new features, new or significantly updated services, new or significantly updated APIs, etc. and may be incompatible with previous releases (major or minor).   Minor releases may contain some new or updated functionality but should always be backward compatible with the associated Major and Minor releases it is based on.  Minor Minor releases have a version number which includes a Major release number, a decimal, and a minor release number (like 1.1, 2.1, 2.3, etc.).   Patches (or Patch releases) are releases that contain backward compatible bug fixes.  Patches Patches should not contain any new or updated features except those necessary to address the bug(s).  Patch Patch versions are based on a major version number, a minor version number (or zero if the patch is to the original major version, and a patch version (like 1.0.1, 1.2.1, 2.1.1, etc.) with decimals between these numbers. EdgeX has automated pre-release versions with suffixes to speed up integration and testing between the different components. These suffixes are, “dev.X” (where X is a number) to denote a developmental release and “rc.X” to denote a release candidate.

Pre-release Versions and the Release Cycle

Automated pre-release versions are released during the release cycle. During normal development time the releases will be marked with the suffix “-dev.X” (where X is a number) denoting a developmental release. Once EdgeX has entered a code freeze the automated releases will be tagged with the suffix “-rc.X” (where X is a number) to denote a release candidate. For components that have their own release cycles, the working group chair should decide when code freeze starts. When a component is ready for release, developers should inform the working group chairperson that manages the component. It will be up to the working group chairperson and the release manager to decide when to cut the release for the component. Once the release is cut the version will be updated to the next semantic version and the suffix will revert to “-dev.X” until the next code freeze.
The “next” semantic version can increase the major, minor or patch version of the component. If the TSC has already decided on the version number for the next named release (Ex: Delhi is 0.7 and Edinburgh is 1.0) the component should be set at that version. If the TSC has not decided on the version number for the next named release, then the working group chairperson and release manager can increase the patch version. It is recommended to wait until the TSC has decided the next version to release the component. However, for certain components that are released on their own release cycle (ie: SDKs) this may not be viable. For core releases during code freeze EdgeX will cut a release branch. For each repository, once the named release branch is cut then the master branch will be increased to the next forecasted version. From this point forward, the release branch will only be allowed to increase its patch version to not break the semantic versioning.

Versioning and the Release Cycle

...