From 8e01d860bf42da5aa26d74d3b1b676023a8679d9 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 1 Sep 2022 17:11:21 -0500 Subject: [PATCH 1/3] Codify that we may stop publishing artifacts, and change unstable portions of otherwisse stable APIs --- VERSIONING.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index 3346bad0d36..0a7716bcaee 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -18,7 +18,7 @@ changes are: reordering parameters, adding a method to an interface or abstract class without adding a default implementation. -- ABI changes that could require code using the artifact to be recompiled, but not changed, e.g., +- API changes that could require code using the artifact to be recompiled, but not changed, e.g., changing the return type of a method from `void` to non-`void`, changing a `class` to an `interface`. The [JLS](https://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html) has more information on what constitutes compatible changes. @@ -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 its 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, 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 From 468b103d3e5e8745a0d2f385afbad1918ca64757 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 2 Sep 2022 08:04:16 -0500 Subject: [PATCH 2/3] Revert ABI -> API --- VERSIONING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index 0a7716bcaee..e6fd681bf3e 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -18,7 +18,7 @@ changes are: reordering parameters, adding a method to an interface or abstract class without adding a default implementation. -- API changes that could require code using the artifact to be recompiled, but not changed, e.g., +- ABI changes that could require code using the artifact to be recompiled, but not changed, e.g., changing the return type of a method from `void` to non-`void`, changing a `class` to an `interface`. The [JLS](https://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html) has more information on what constitutes compatible changes. From f1d8bae8aeba14955acbcc4a105ee0ffe36ccb4a Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 7 Sep 2022 11:01:27 -0500 Subject: [PATCH 3/3] PR feedback --- VERSIONING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index e6fd681bf3e..9d2ad3af3cf 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -35,7 +35,7 @@ A stable artifact may depend on an `-alpha` artifact, and expose classes, interf 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 its own implementation +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. @@ -53,8 +53,8 @@ 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, the BOM will continue to reference the last published version of the -artifact, and the API of the last published version will remain stable. +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