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

Author: jack-berg

VERSIONING.md

@@ -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