PROPOSED draft to be reviewed and approved by the TSC. Not official or final yet. This policy will be used to govern EdgeX Edinburgh release and all following releases.
Document editors - highlight changes and fictes fixes.
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’). EdgeX micro services that are part of this collection include:
- Core Data
- Metadata
- Command
- Registry/Configuration
- Logging
- Scheduler
- Notifications
- Rules Engine
- Export Client and Distro Services
- Security Services (API Gateway, Secret Store)
- System Management Services
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 release is before the Fuji release, which is before Geneva release, etc. The EdgeX release code names are based on geographical locations.
These releases also get a version number. For example, the Delhi release was version 0.7. 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, 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.
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 decision is pending.
Independent Tools and Services Release Cycle/Cadence
Some EdgeX services (and tooling) have a separate release cycle. The Device Service SDKs and Device Services, 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
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.
Major, Minor Versions and Patches
Again, EdgeX follows semantic versioning. Major releases have a “major number” or version number like 1.0, 2.0, etc. 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 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 should not contain any new or updated features except those necessary to address the bug(s). 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 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 a minor version. 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 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 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 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 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 artifacts are used by the developer and user community to demonstrate and test upcoming release functionality and changes. These artifacts 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).