From 66285e2cbeb618a1f087eafe2a1a453305ae301f Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Wed, 7 Sep 2022 11:43:55 -0500 Subject: [PATCH] =?UTF-8?q?Codify=20that=20we=20may=20stop=20publishing=20?= =?UTF-8?q?artifacts,=20and=20change=20unstable=20por=E2=80=A6=20(#4729)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Codify that we may stop publishing artifacts, and change unstable portions of otherwisse stable APIs * Revert ABI -> API * PR feedback --- VERSIONING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/VERSIONING.md b/VERSIONING.md index 3346bad0d36..9d2ad3af3cf 100644 --- a/VERSIONING.md +++ b/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