...
Document under development. See https://docs.google.com/document/d/1EzaAxj7Henl-ep8_5wLrZUQYtelpwxkqIVbJvEHvlfI for current revisions and edits under consideration.
...
Release Cycle / Cadence
The EdgeX Foundry community publishes new releases of EdgeX services on a regular cadence, enabling the community, businesses and developers to plan their roadmaps with certainty of access to new features.
Releases of the collection of central or core EdgeX micro services get a development codename (example: ‘Edinburgh’ ‘Edinburgh’). EdgeX micro services that are part of this collection include:
Core Data
Metadata
Command
Registry/Configuration (Consul)
Logging
Scheduler
Notifications
Rules Engine
Export Client and Distro Services
Security Services
(API Gateway
(Kong)
Secret Store (Vault)
System Management Services
Additional supporting infrastructure for these services
Database (Mongo or Redis today)
Bootstrapping/initialization services
Configuration (config-seed)
For the purposes of the rest of this document, the term “EdgeX release” refers to the release of this collection of central EdgeX micro services. The EdgeX release code name is sequential in that the code names are alphabetical. The Edinburgh The Edinburgh release is before the Fuji Fuji release, which is before Geneva Geneva release, etc. The The EdgeX release code names are based on geographical locations. These releases also get a version number. For For example, the Delhi release was version 0.7. EdgeX EdgeX releases the collection of central or core EdgeX micro services twice a year (typically around April and October).
EdgeX's versioning scheme is based on semantic versioning (https://semver.org/). However 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 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 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.
Note, it is not determined whether the new Application Services will be part of the EdgeX release or live as independent tools and services (as defined below). TSC TSC decision is pending.
Independent Tools and Services Release Cycle/Cadence
Some EdgeX services (and tooling) have a separate release cycle. The The Device Service SDKs and Device Services, for example, are not necessarily released with the EdgeX release. Which Which services are allowed to have their own release cycles is at the discretion of the EdgeX Technical Steering Committee (TSC). Services 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 Today, the following tools and services are released on independent release cycles:
Device Service SDKs (Go and C)
Device Services
When appropriate, a working group chairperson requests permission to release these tools and services. The The release manager, at the request of the working group chairperson, are responsible for the release of these tools and services. Again 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 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 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 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 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 and Patches
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.
Versioning and the Release Cycle
At the conclusion of each EdgeX release, the TSC meets and forecasts the version (major or minor) for the next release cycle. Based on the functionality to be implemented and included with the upcoming release, the EdgeX TSC may choose to preliminarily version the next release as a major release. If If the next release will contain only backward compatible changes and deemed not to contain a significant amount of new and updated features, the TSC may choose to version the upcoming release as a minor version. For For example, if the current release – codenamed "Portville" was a major version 7.0, the TSC may choose to set the next release to major version 8.0 (if they plan to include non-compatible changes or if the amount of new and updated functionality is significant enough to want to distinguish the release as a major release) or as a minor version 7.1 (indicating no changes that break compatibility with the prior named release).
All the VERSION files (on the current Master branch of the repositories) along with any other relevant indicators in the project repositories will immediately be updated to indicate this TSC decision.
Some event during the release cycle could dictate the TSC to change the version decision made at the start of a release. This This could be from major to minor or from minor to major release. A decision to change the version strategy in the middle of the release cycle is not one that is done casually, should be avoided at all costs, and will cause a certain amount of hardship on the developers and confusion to users (example: development artifacts in repositories like Nexus or Docker would suddenly change and make it look like a new release was created). Below Below are some examples of when the TSC may change the version decision:
When an unforeseen technical challenge arises and the best technical solution as decided by the TSC requires non-backward compatible change (forcing the next version to be a major version vs minor).
When, nearing the completion of the release cycle it is discovered that compatibility remains yet it was expected that the release would require a non-compatible change (allowing under some circumstances for the TSC to return to a minor version vs major)
When an expected feature associated with the release is not going to make the release deadline and causes the TSC to re-evaluate the versioning (again more likely going from major to minor)
The TSC should not generally make changes to the release/version strategy during the release cycle due to non-technical issues or concerns (example a marketing request to make a major version).
The The incorporation of non-technical issues affecting the version decisions should only be taken into consideration during release planning.
Release Manager & Patch Decisions
On the TSC's decision to forecast the upcoming version for the next release cycle, the management, coordination and orchestration of the release cycle is turned over to the release manager.
Decisions about patches (versions made between the release cycle that are used for for backwards-compatible bug fixes) are at the discretion of the release manager for that release cycle. A A work group chairperson can make the request for a patch release, but the decision lies with the release manager. Disagreement can be appealed to the full TSC for adjudication. The release manager must coordinate the patch release with all applicable working groups (via the chairman) - thus the reason a working group chairperson is not unilaterally allowed to produce a release.This next section is still under review by DevOps and LF for impact to CI/CD and other operations.
The release manager can coordinate "pre-release" versions of the artifacts in the middle of the release cycle. These These artifacts are used by the developer and user community to demonstrate and test upcoming release functionality and changes. These These artifacts and source code use a version string containing a hyphen followed by an arbitrary string (like -dev, -test, -{timestamp}, etc.) to distinguish them from the final release of that version (see paragraph 9 of the semantic versioning specification for more background).