Skip to content

Commit

Permalink
[VERSIONING.md] Reorganize and clarify compatibility guarantees (#8812)
Browse files Browse the repository at this point in the history 
**Description:** Reorganize `VERSIONING.md`, specify compatibility
guarantees that have already been discussed and answer questions on
#8002.

Three new guarantees in the document had already been discussed
elsewhere:

- String representation:
#7625 (comment)
- Go version compatibility: Mentioned [on
README.md](https://github.com/open-telemetry/opentelemetry-collector?tab=readme-ov-file#compatibility)
- Dependency updates: Discussed in private, most recently in relation to
whether #7095 should block `pdata`'s 1.0 (consensus seems to be that it
should not).

Regarding the questions mentioned on #8002:

> Does adding new validation rules mean a breaking change?

Generally, yes except when the configuration was already invalid (i.e.
the Collector did not work properly with it).

> Should we offer a "NewDefault...." for each config and say that the
behavior of the config is stable only if initialized with NewDefault?

I did not add anything for this one. I think we should discuss it, but:
- I don't think there is a sensible output for `NewDefault...` for all
configurations (e.g. for `confignet.TCPAddr`, what would the default
be?)
- It seems to me that we should handle configuration validity through
`Validate`, and not through `NewDefault...`. `NewDefault` may help but
ultimately we need to verify through `Validate`.

> Is adding new fields means breaking change? Let's assume someone
"squash" the message into another message, then adding a field with same
mapstruct value will be a breaking change, what do we do with that? What
are the rules we follow.

This was already in this document, where we had decided that adding new
fields was okay. I think it would be too stringent to bar us from adding
new fields.

**Link to tracking Issue:** Fixes #8002

---------

Co-authored-by: Yang Song <[email protected]>
  • Loading branch information
@mx-psi @songy23
mx-psi and songy23 authored Dec 11, 2023
1 parent b0f618e commit a5cb92a
Showing 1 changed file with 52 additions and 34 deletions.
86 changes: 52 additions & 34 deletions VERSIONING.md
View file
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.
* **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.

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

0 comments on commit a5cb92a

Please sign in to comment.