Document our compatibility promise

[pellared]

This is inspired by how the Go standard library handles such issues. See: https://pkg.go.dev/time#Time

I would say we do our best to follow https://go.dev/doc/go1compat which is kind of:

what compiled in the past should compile in the future

with some exceptions.

The Collector does have it documented here: https://github.com/open-telemetry/opentelemetry-collector/blob/main/VERSIONING.md#go-modules

Probably we should also document it in our https://github.com/open-telemetry/opentelemetry-go/blob/main/VERSIONING.md

Originally posted by @pellared in #6272 (comment)

[MrAlias]

We are already pretty clear on this. We state:

• Versioning of this project will be idiomatic of a Go project using Go
  modules.
  • Semantic import
    versioning
    will be used.

    • Versions will comply with semver
      2.0 with the following exceptions.

      • New methods may be added to exported API interfaces. All exported
        interfaces that fall within this exception will include the following
        paragraph in their public documentation.

        Warning: methods may be added to this interface in minor releases.

    • If a module is version v2 or higher, the major version of the module
      must be included as a /vN at the end of the module paths used in
      go.mod files (e.g., module go.opentelemetry.io/otel/v2, require go.opentelemetry.io/otel/v2 v2.0.1) and in the package import path
      (e.g., import "go.opentelemetry.io/otel/v2/trace"). This includes the
      paths used in go get commands (e.g., go get go.opentelemetry.io/otel/[email protected]). Note there is both a /v2 and a
      @v2.0.1 in that example. One way to think about it is that the module
      name now includes the /v2, so include /v2 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.

Semantic import versioning pretty clearly states:

If an old package and a new package have the same import path, the new package must be backwards compatible with the old package.

We have listed our only exception to this rule in the API. We do not allow this rule to be broken in a post v0 module without a vN+1 release.

Adding additional documentation would likely only add clutter.

[pellared]

I thought just about referring to https://go.dev/doc/go1compat to say that it describes how we understand "breaking changes".

I think that it would be helpful to some users and contributors.

Maybe reusing what the Collector SIG did would be good.

P.S. link to https://github.com/golang/go/wiki/Modules could be updated..I think that it's content is also a little dated.

[MrAlias]

Gotcha. Sounds good 👍