open-telemetry
/
opentelemetry-java
mirror of https://github.com/open-telemetry/opentelemetry-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Codify that we may stop publishing artifacts, and change unstable por… (#4729) 

* Codify that we may stop publishing artifacts, and change unstable portions of otherwisse stable APIs

* Revert ABI -> API

* PR feedback
This commit is contained in:
jack-berg 2022-09-07 11:43:55 -05:00 committed by GitHub
parent 57b05cb71d
commit 66285e2cbe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
VERSIONING.md
View File

@ -31,6 +31,17 @@ changes are:
Such changes will be avoided - if they must be made, the `MAJOR` version of the artifact will be
incremented.
A stable artifact may depend on an `-alpha` artifact, and expose classes, interfaces, enums, etc. of
the `-alpha` artifact as part of its public API. In these cases, the stable artifact will place
an [implementation](https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation)
dependency (as opposed to an api dependency) on the `-alpha` artifact. In order to consume the
portions of the API related to the `-alpha` artifact, a user must place their own implementation
dependency on it. In adding the implementation dependency, the user has opted into to using
an `-alpha` artifact, and we reserve the right to change the portions of the API pertaining to
the `-alpha` artifact. This includes changing the names of methods, return types, argument types, etc.
We will use this technique sparingly and only when there is some significant reduction in friction
by including the `-alpha` artifact.
Backwards incompatible changes to `internal` packages are expected. Versions of published artifacts
are expected to be aligned by using BOMs we publish. We will always provide BOMs to allow alignment
of versions.
@ -39,6 +50,12 @@ Changes may be made that require changes to the an app's dependency declarations
incrementing the version on `MINOR` version updates. For example, code may be separated out to a
new artifact which requires adding the new artifact to dependency declarations.
On rare occasions we may deprecate an entire stable artifact, with the intent of stopping functional
changes or enhancements. In these situations we may stop publishing additional `MINOR` or `MAJOR`
versions of the artifact. However, if necessary, we'll publish security fixes via `PATCH` releases.
Despite stopping publishing, new versions of the BOM will continue to reference the last published
version of the artifact, and the API of the last published version will remain stable.
As a user, if you always depend on the latest version of the BOM for a given `MAJOR` version, and
you do not use classes in the `internal` package (which you MUST NOT do), you can be assured that
your app will always function and have access to the latest features of OpenTelemetry without needing