cpp_client_telemetry/docs/versioning.md

Release and Version strategy

Microsoft 1DS C/C++ Client Telemetry project releases are published monthly. If urgent critical fix is needed, then additional release could be published ahead of schedule.

Autogenerated Version

SDK utilizes SemVer 2.0 for its versioning.

SDK version as of September 2021 is v3.5.200, where:

• VER_MAJOR=3
• VER_MINOR=5
• VER_PATCH=200 with Version.hpp containing runtime-accessible version information. Version.hpp file is auto-generated.

Version details:

• VER_MAJOR is 3. Release 4 ETA is 2021-2022.
• VER_MINOR is 4. This number has to be incremented to 5 on January 1st, 2021.
• VER_PATCH is a day number of the year.

Version.hpp file is generated during Release publishing stage using cross-platform gen-version script written in node.js.

Release Process

SDK maintainer preparing the release must:

• run tools/gen-version.cmd on Windows (or tools/gen-version.sh on POSIX) to generate the Version.hpp file
• commit the contents of Version.hpp
• send a PR to merge it in the main branch
• use GitHub Release Management Tab to create a corresponding v3.x.x release tag with release notes

Only source code release is published in .zip or tarball under Release tab. No binary artifacts published in this repository.

Products using this SDK may subsequently:

• refresh their custom product branches and mirrors based on latest published release tag
• publish their Windows build, NuGet packages, Android / Maven artifacts, cocoapods for Mac and iOS, etc.

There are no immediate plans to start publishing binary packages. This may change in 2021.

SDK Version and API / ABI stability guarantees

C++ API

C++ SDK does not provide ABI stability guarantee. However, MAJOR version generally provides compile-time API stability guarantee. Applications that onboarded to SDK v3.x may be easily recompiled against any version of SDK v3.y, where y>=x (unless otherwise noted in Release Notes). There are exceptional cases where modules API may change. In those exceptional cases - developers may need to implement some minor modifications to their instrumented code.

We strive for stability and long-term guarantees. Core API-breaking changes are strongly discouraged. Any API-breaking change MUST be accompanied by a clear guidance and documentation in markdown format published under the /docs directory.

Usage of deprecated attribute is encouraged to gradually phase out old methods. However, since the SDK codebase is still relying on C++11 compiler - SDK should declare a macro to dynamically alias the [[deprecated]] attribute that is only available starting with C++14 - see here.

Additive changes are acceptable and encouraged. Any significant additive change that implements a major feature, such as completely new interface SHOULD be accompanied by increment of a corresponding MINOR version. In some cases where an addition is rather minor and insignficant, it is acceptble to increment PATCH version only. Developers and maintainers must use their best judgement to decide on where MINOR increment is warranted.

C API

C API is designed for plugins, or "SDK in SDK" scenarios and provides ABI stability guarantee.

C API is described in mat.h C header.

C API is forward-compatible and backwards-compatible: unsupported API calls are ignored and an error returned to the caller. Current version of C API is 3.1.0 with no immediate upgrade plans. Any changes to memory layout of C structs must be extremely carefully vetted with various products using C API. Adding new C functions to C API should warrant an upgrade of C API to version 3.2.0. Since C API is rather stable and does not change frequently, it may be missing some features recently added to C++ API.

Tentative Release schedule for 2021H2

Release tag	ETA Date	Branch
v3.5.[240-270]	Sept 2021	main
v3.5.[271-300]	Oct 2021	main
v3.5.[301-330]	Nov 2021	main
v3.6.[1-30]	Dec 2021	main

NOTE: although this tentative schedule lists v3.5 or v3.6, we live in agile environment. Due to various arising practical needs it may be necessary to update VER_MINOR to 7, 8, 9, etc. in case of a need to add some new major feature or new protocol to SDK.

Release schedule for 2022H1

A separate feature branch may be needed to accommodate the integration with OpenTelemetry C++ SDK. Separate branch with addition of new major API changes should be labeled dev/r4 to mark the Release 4.x milestone. Next major release 4 may contain API-breaking changes. Those changes must be accompanied by a corresponding shim layer, automatic code upgrade scripts, or manual upgrade instructions. There is no intent to force existing customers to entirely reinstrument their code. Backwards compatibility and solid long-term upgrade planning is a fundamental principle of 1DS SDK design.

Product Release branches

Microsoft products onboarded to 1DS C/C++ SDK may release their own product branches, such as release/product with git tags as v3.5.1-rc0. Custom product branches may contain tweaks to API and SDK features not applicable to mainline main branch. However, should the products see the common need for their custom features - developers are encouraged to integrate their patches back to mainline main branch.

Forking of this repo on GitHub is not enabled and not encouraged for Microsoft products. Microsoft products may mirror the SDK code to their own repository of choice, maintaining their custom changes, including their private closed-source additions to SDK. Products may promote their custom changes made to SDK back to mainline 1DS C++ SDK repository as-needed and where applicable.

Supportability Policy

We accept issues reported against releases that were published within the last 12 months. Customers are strongly encouraged to intake the latest stable SDK release at least once in 6 months. All published releases are considered stable.