From 06432d0cdf5bcbafbad32fd6998dca6efacf81e8 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Tue, 7 Nov 2023 13:53:46 +0100 Subject: [PATCH 1/4] [VERSIONING.md] Reorganize and clarify compatibility guarantees --- VERSIONING.md | 81 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 33 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index 08e1b9ca547..bba9f1112e2 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -5,7 +5,52 @@ is designed so that the following goal can be achieved: **Users are provided a codebase of value that is stable and secure.** -## Policy +## Public API expectations + +The following public API expectations apply to all modules in opentelemetry-collector and opentelemetry-collector-contrib. +As a general rule, stability guarantees of modules versioned as `v1` or higher are aligned with [Go 1 compatibility promise](https://go.dev/doc/go1compat). + +### General Go API considerations + +OpenTelemetry authors reserve the right to introduce API changes breaking compatibility between minor versions in the following scenarios: + * **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed + struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change. + However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend + using OpenTelemetry collector structs with the keyed literals only. + * **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances, + such as when the type is embedded in a struct along with another type, the addition of the new method may + break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect + against this rare case and do not guarantee compatibility in such scenarios. + * **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package + in future releases may conflict with other names defined in the program. We do not recommend the use of + `import .` with OpenTelemetry Collector modules. + +Unless otherwise specified in the documentation, the following may change in any way between minor versions: + * **String representation**. The `String` method of any struct is intended to be human-readable and may change its output + in any way. + * **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change. + * **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the + public API or the update may change the behavior of applications in an incompatible way. + +### Configuration structures + +Configuration structures are part of the public API and backwards +compatibility should be maintained through any changes made to configuration structures. + +Unless otherwise specified in the documentation, the following may change in any way between minor versions: + * **Adding new fields to configuration structures**. Because configuration structures are typically instantiated through + unmarshalling a serialized representation of the structure, and not through structure literals, additive changes to + the set of exported fields in a configuration structure are not considered to break backward compatibility. + +The following are explicitly considered to be breaking changes: + * **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`, + `mapstructure:`, etc) are part of the structure definition and must maintain compatibility to the same extent as the + structure. + * **Making validation rules more strict**. A valid configuration struct as defined by its `Validate` method return value + must continue to be valid after a change to the validation rules, except when the configuration struct would cause an error + on its intended usage (e.g. when calling a method or when passed to any method or function in any module under opentelemetry-collector). + +## Versioning and module schema * Versioning of this project will be idiomatic of a Go project using [Go modules](https://golang.org/ref/mod#versions). @@ -32,7 +77,7 @@ is designed so that the following goal can be achieved: * A single module should exist, rooted at the top level of this repository, that contains all packages provided for use outside this repository. * Additional modules may be created in this repository to provide for - isolation of build-time tools or other commands. Such modules should be + isolation of build-time tools, other commands or independent libraries. Such modules should be versioned in sync with the `go.opentelemetry.io/collector` module. * Experimental modules still under active development will be versioned with a major version of `v0` to imply the stability guarantee defined by @@ -40,16 +85,6 @@ is designed so that the following goal can be achieved: > Major version zero (0.y.z) is for initial development. Anything MAY > change at any time. The public API SHOULD NOT be considered stable. - - * Configuration structures should be considered part of the public API and backward - compatibility maintained through any changes made to configuration structures. - * Because configuration structures are typically instantiated through unmarshalling - a serialized representation of the structure, and not through structure literals, - additive changes to the set of exported fields in a configuration structure are - not considered to break backward compatibility. - * Struct tags used to configure serialization mechanisms (`yaml:`, `mapstructure:`, etc) - are to be considered part of the structure definition and must maintain compatibility - to the same extent as the structure. * Versioning of the associated [contrib repository](https://github.com/open-telemetry/opentelemetry-collector-contrib) of this project will be idiomatic of a Go project using [Go @@ -72,14 +107,8 @@ is designed so that the following goal can be achieved: whenever you are using the module name). * If a module is version `v0` or `v1`, do not include the major version in either the module path or the import path. - * Configuration structures should be considered part of the public API and backward - compatibility maintained through any changes made to configuration structures. - * Because configuration structures are typically instantiated through unmarshalling - a serialized representation of the structure, and not through structure literals, - additive changes to the set of exported fields in a configuration structure are - not considered to break backward compatibility. * Modules will be used to encapsulate receivers, processor, exporters, - extensions, and any other independent sets of related components. + extensions, connectors and any other independent sets of related components. * Experimental modules still under active development will be versioned with a major version of `v0` to imply the stability guarantee defined by [semver](https://semver.org/spec/v2.0.0.html#spec-item-4). @@ -102,17 +131,3 @@ is designed so that the following goal can be achieved: * Contrib modules will be kept up to date with this project's releases. * GitHub releases will be made for all releases. * Go modules will be made available at Go package mirrors. -* Stability guaranties of modules versioned as `v1` or higher are aligned with [Go 1 compatibility - promise](https://go.dev/doc/go1compat). OpenTelemetry authors reserve the right to introduce API changes breaking - compatibility between minor versions in the following scenarios: - * **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed - struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change. - However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend - using OpenTelemetry collector structs with the keyed literals only. - * **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances, - such as when the type is embedded in a struct along with another type, the addition of the new method may - break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect - against this rare case and do not guarantee compatibility in such scenarios. - * **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package - in future releases may conflict with other names defined in the program. We do not recommend the use of - `import .` with OpenTelemetry Collector modules. From 197bce563d28ae98d11604561948e521435947f5 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Tue, 7 Nov 2023 14:10:15 +0100 Subject: [PATCH 2/4] Fix formatting --- VERSIONING.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index bba9f1112e2..2811184867f 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -13,24 +13,24 @@ As a general rule, stability guarantees of modules versioned as `v1` or higher a ### General Go API considerations OpenTelemetry authors reserve the right to introduce API changes breaking compatibility between minor versions in the following scenarios: - * **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed - struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change. - However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend - using OpenTelemetry collector structs with the keyed literals only. - * **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances, - such as when the type is embedded in a struct along with another type, the addition of the new method may - break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect - against this rare case and do not guarantee compatibility in such scenarios. - * **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package - in future releases may conflict with other names defined in the program. We do not recommend the use of - `import .` with OpenTelemetry Collector modules. +* **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed + struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change. + However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend + using OpenTelemetry collector structs with the keyed literals only. +* **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances, + such as when the type is embedded in a struct along with another type, the addition of the new method may + break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect + against this rare case and do not guarantee compatibility in such scenarios. +* **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package + in future releases may conflict with other names defined in the program. We do not recommend the use of + `import .` with OpenTelemetry Collector modules. Unless otherwise specified in the documentation, the following may change in any way between minor versions: - * **String representation**. The `String` method of any struct is intended to be human-readable and may change its output - in any way. - * **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change. - * **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the - public API or the update may change the behavior of applications in an incompatible way. +* **String representation**. The `String` method of any struct is intended to be human-readable and may change its output + in any way. +* **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change. +* **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the +public API or the update may change the behavior of applications in an incompatible way. ### Configuration structures @@ -38,17 +38,17 @@ Configuration structures are part of the public API and backwards compatibility should be maintained through any changes made to configuration structures. Unless otherwise specified in the documentation, the following may change in any way between minor versions: - * **Adding new fields to configuration structures**. Because configuration structures are typically instantiated through - unmarshalling a serialized representation of the structure, and not through structure literals, additive changes to - the set of exported fields in a configuration structure are not considered to break backward compatibility. +* **Adding new fields to configuration structures**. Because configuration structures are typically instantiated through +unmarshalling a serialized representation of the structure, and not through structure literals, additive changes to +the set of exported fields in a configuration structure are not considered to break backward compatibility. The following are explicitly considered to be breaking changes: - * **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`, - `mapstructure:`, etc) are part of the structure definition and must maintain compatibility to the same extent as the - structure. - * **Making validation rules more strict**. A valid configuration struct as defined by its `Validate` method return value - must continue to be valid after a change to the validation rules, except when the configuration struct would cause an error - on its intended usage (e.g. when calling a method or when passed to any method or function in any module under opentelemetry-collector). +* **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`, +`mapstructure:`, etc) are part of the structure definition and must maintain compatibility to the same extent as the +structure. +* **Making validation rules more strict**. A valid configuration struct as defined by its `Validate` method return value +must continue to be valid after a change to the validation rules, except when the configuration struct would cause an error +on its intended usage (e.g. when calling a method or when passed to any method or function in any module under opentelemetry-collector). ## Versioning and module schema From 7f9823265df7550ae455dd9c642fcdc9bfe57854 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Thu, 9 Nov 2023 11:18:16 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Yang Song --- VERSIONING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index 2811184867f..809a1bdfac1 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -107,7 +107,7 @@ on its intended usage (e.g. when calling a method or when passed to any method o whenever you are using the module name). * If a module is version `v0` or `v1`, do not include the major version in either the module path or the import path. - * Modules will be used to encapsulate receivers, processor, exporters, + * Modules will be used to encapsulate receivers, processors, exporters, extensions, connectors and any other independent sets of related components. * Experimental modules still under active development will be versioned with a major version of `v0` to imply the stability guarantee defined by From 559d4af738f8b12e79a3ae65edb6f26db9410899 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Thu, 9 Nov 2023 11:27:31 +0100 Subject: [PATCH 4/4] Address comments --- VERSIONING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/VERSIONING.md b/VERSIONING.md index 809a1bdfac1..e0dcc6781b5 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -29,6 +29,7 @@ Unless otherwise specified in the documentation, the following may change in any * **String representation**. The `String` method of any struct is intended to be human-readable and may change its output in any way. * **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change. +* **OS version compatibility**. Removing support for an unsupported OS version is not considered a breaking change. Upgrading or downgrading OS version support per the [platform support](docs/platform-support.md) document is not considered a breaking change. * **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the public API or the update may change the behavior of applications in an incompatible way. @@ -41,6 +42,8 @@ Unless otherwise specified in the documentation, the following may change in any * **Adding new fields to configuration structures**. Because configuration structures are typically instantiated through unmarshalling a serialized representation of the structure, and not through structure literals, additive changes to the set of exported fields in a configuration structure are not considered to break backward compatibility. +* **Relaxing validation rules**. An invalid configuration struct as defined by its `Validate` method return value +may become valid after a change to the validation rules. The following are explicitly considered to be breaking changes: * **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`,