From 31294750ceca2ebfe60fdc3ed345d858702efd43 Mon Sep 17 00:00:00 2001 From: Bob Strecansky Date: Thu, 17 Dec 2020 13:56:27 -0500 Subject: [PATCH 1/4] Semantic Versioning Rationale --- README.md | 4 ++++ docs/versioning.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 docs/versioning.md diff --git a/README.md b/README.md index 808feeb51..46ac73461 100644 --- a/README.md +++ b/README.md @@ -86,3 +86,7 @@ The easy way to test the example out with docker and docker-compose is: 3.) Go to Graph section, type "opentelemetry_prometheus_counter" in the search field or select it in the dropdown menu. You will see the counter value. Every other time you run `make metrics-prometheus-example` will increment the counter but remember that Prometheus scrapes values once in 10 seconds. 4.) In order to stop docker containers for this example just run `make stop-prometheus` + +## Versioning + +Versioning rationale can be found in the [Versioning Documentation](/docs/versioning.md) diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 000000000..3ef953b9d --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,29 @@ +### Assumptions +This project uses [semver v2](https://semver.org/), as does the rest of OpenTelemetry. + +### Goals +#### API Stability: +* Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function, with any SDK that has the same major version, and equal or greater minor or patch version. + * example: libraries that are instrumented with opentelemetry-api-trace:1.0.1 will function with SDK library opentelemetry-sdk-trace:1.11.33. +* No existing method names or signatures will change with patch versioning. We will only change signatures in a backwards compatible way with minor versioning. + +#### SDK Stability: +* Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. +* Internal interfaces are allowed to break. +* No existing method names or signatures will change with patch versioning. We will only change signatures in a backwards compatible way with minor versioning. + +### Methods +#### Mature signals +* Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. +* Internal interfaces are allowed to break. +* API modules for mature (i.e. released) signals will be transitive dependencies of the OpenTelemetry API class. +* Methods for accessing mature APIs will be added, as appropriate to the OpenTelemetry interface. +* SDK modules for mature (i.e. released) signals will be transitive dependencies of the SDK. +* Configuration options for the SDK modules for mature signals will be exposed, as appropriate, on the OpenTelemetry SDK class. + +#### Immature or experimental signals +* API namespaces for immature signals will not be transitive dependencies of the API class. +* API namespaces will be named with an "-experimental" suffix to make it abundantly clear that depending on them is at your own risk. +* API namespaces for immature signals will be co-versioned along with mature API namespaces. +* The classes for immature APIs will be used as if they were mature signals. This will enable users to easily transition from immature to mature usage, without having to change imports. +* SDK classes for immature signals will also be named with an "-experimental" suffix, in parallel to their API modules. From 1cebf65abaf65287781fa4ce8a833730e2da6077 Mon Sep 17 00:00:00 2001 From: Bob Strecansky Date: Fri, 18 Dec 2020 08:13:01 -0500 Subject: [PATCH 2/4] Update docs/versioning.md Co-authored-by: Daniel Dyla --- docs/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioning.md b/docs/versioning.md index 3ef953b9d..7dc3a1e04 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -3,7 +3,7 @@ This project uses [semver v2](https://semver.org/), as does the rest of OpenTele ### Goals #### API Stability: -* Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function, with any SDK that has the same major version, and equal or greater minor or patch version. +* Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function with any SDK that has the same major version and an equal or greater minor version. * example: libraries that are instrumented with opentelemetry-api-trace:1.0.1 will function with SDK library opentelemetry-sdk-trace:1.11.33. * No existing method names or signatures will change with patch versioning. We will only change signatures in a backwards compatible way with minor versioning. From 4458d60eda48d07994ea9c352469e2eef4ff1de4 Mon Sep 17 00:00:00 2001 From: Bob Strecansky Date: Fri, 18 Dec 2020 08:25:41 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Daniel Dyla --- docs/versioning.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/versioning.md b/docs/versioning.md index 7dc3a1e04..865bc9d1e 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -5,12 +5,14 @@ This project uses [semver v2](https://semver.org/), as does the rest of OpenTele #### API Stability: * Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function with any SDK that has the same major version and an equal or greater minor version. * example: libraries that are instrumented with opentelemetry-api-trace:1.0.1 will function with SDK library opentelemetry-sdk-trace:1.11.33. -* No existing method names or signatures will change with patch versioning. We will only change signatures in a backwards compatible way with minor versioning. +* No existing method names or signatures will change with a patch release. +* Method signatures may only change in a backwards compatible way with a minor release. #### SDK Stability: * Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. -* Internal interfaces are allowed to break. -* No existing method names or signatures will change with patch versioning. We will only change signatures in a backwards compatible way with minor versioning. +* Internal interfaces may break with a minor version change. +* No existing public method names or signatures will change with a patch release. +* Public method signatures may only change in a backwards compatible way with a minor release. ### Methods #### Mature signals From bcc857747b667f7754eab313e7371533735b8827 Mon Sep 17 00:00:00 2001 From: Bob Strecansky Date: Sat, 19 Dec 2020 15:35:54 -0500 Subject: [PATCH 4/4] Daniel Dyla Suggestions --- docs/versioning.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/versioning.md b/docs/versioning.md index 865bc9d1e..e1344070c 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -10,7 +10,6 @@ This project uses [semver v2](https://semver.org/), as does the rest of OpenTele #### SDK Stability: * Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. -* Internal interfaces may break with a minor version change. * No existing public method names or signatures will change with a patch release. * Public method signatures may only change in a backwards compatible way with a minor release. @@ -19,13 +18,12 @@ This project uses [semver v2](https://semver.org/), as does the rest of OpenTele * Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. * Internal interfaces are allowed to break. * API modules for mature (i.e. released) signals will be transitive dependencies of the OpenTelemetry API class. -* Methods for accessing mature APIs will be added, as appropriate to the OpenTelemetry interface. +* Methods for accessing mature APIs will be added, as appropriate to the OpenTelemetry API interface. * SDK modules for mature (i.e. released) signals will be transitive dependencies of the SDK. * Configuration options for the SDK modules for mature signals will be exposed, as appropriate, on the OpenTelemetry SDK class. #### Immature or experimental signals * API namespaces for immature signals will not be transitive dependencies of the API class. * API namespaces will be named with an "-experimental" suffix to make it abundantly clear that depending on them is at your own risk. -* API namespaces for immature signals will be co-versioned along with mature API namespaces. * The classes for immature APIs will be used as if they were mature signals. This will enable users to easily transition from immature to mature usage, without having to change imports. * SDK classes for immature signals will also be named with an "-experimental" suffix, in parallel to their API modules.