Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[VERSIONING.md] Reorganize and clarify compatibility guarantees #8812

Merged
merged 5 commits into from
Dec 11, 2023
Merged

[VERSIONING.md] Reorganize and clarify compatibility guarantees #8812

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
06432d0
[VERSIONING.md] Reorganize and clarify compatibility guarantees
mx-psi Nov 7, 2023
197bce5
Fix formatting
mx-psi Nov 7, 2023
7f98232
Apply suggestions from code review
mx-psi Nov 9, 2023
559d4af
Address comments
mx-psi Nov 9, 2023
2ca687e
Merge branch 'main' into mx-psi/versioning-guarantees
mx-psi Dec 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 52 additions & 34 deletions VERSIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,55 @@ 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.
Comment on lines +29 to +30
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

* **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does unsupported here mean unsupported by Go or unsupported by us.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Supported by the Go team. This is mostly a rephrasing of what is already on the README https://github.com/open-telemetry/opentelemetry-collector?tab=readme-ov-file#compatibility

* **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.

### 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.
* **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:`,
`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).
Expand All @@ -32,24 +80,14 @@ 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
[semver](https://semver.org/spec/v2.0.0.html#spec-item-4).

> 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
Expand All @@ -72,14 +110,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.
* 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
[semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
Expand All @@ -102,17 +134,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.