[MAINTAINER DOC] Define and document a deprecation process (#1923)

CHANGELOG.md

@@ -33,6 +33,21 @@ Increment the:
   [#1916](https://github.com/open-telemetry/opentelemetry-cpp/pull/1916)
 * [SEMANTIC CONVENTIONS] Upgrade to version 1.17.0
   [#1927](https://github.com/open-telemetry/opentelemetry-cpp/pull/1927)
+* [MAINTAINER DOC] Define and document a deprecation process,
+  [DEPRECATION] Deprecate the Jaeger exporter,
+  implemented by [#1923](https://github.com/open-telemetry/opentelemetry-cpp/pull/1923)
+
+Deprecations:
+
+* [MAINTAINER DOC] Define and document a deprecation process,
+  [#1923](https://github.com/open-telemetry/opentelemetry-cpp/pull/1923)
+  * A new file, [DEPRECATED](./DEPRECATED.md) list all the code currently
+    deprecated.
+  * A new [deprecation process](./docs/deprecation-process.md) details the plan to
+    deprecate and later remove code.
+* [DEPRECATION] Deprecate the Jaeger exporter
+  [#1923](https://github.com/open-telemetry/opentelemetry-cpp/pull/1923)
+  * The Jaeger Exporter is deprecated, see [DEPRECATED](./DEPRECATED.md) for details.
 
 Important changes:
 

CMakeLists.txt

@@ -110,6 +110,8 @@ else()
   )
 endif()
 
+option(WITH_NO_DEPRECATED_CODE "Do not include deprecated code" OFF)
+
 option(WITH_STL "Whether to use Standard Library for C++ latest features" OFF)
 option(WITH_GSL
        "Whether to use Guidelines Support Library for C++ latest features" OFF)
@@ -165,7 +167,7 @@ option(WITH_ELASTICSEARCH
 
 option(WITH_ZPAGES "Whether to include the Zpages Server in the SDK" OFF)
 
-option(WITH_JAEGER "Whether to include the Jaeger exporter" OFF)
+option(WITH_JAEGER "DEPRECATED - Whether to include the Jaeger exporter" OFF)
 
 option(WITH_NO_GETENV "Whether the platform supports environment variables" OFF)
 
@@ -240,6 +242,12 @@ function(install_windows_deps)
 endfunction()
 
 if(WITH_JAEGER)
+  if(WITH_NO_DEPRECATED_CODE)
+    message(FATAL_ERROR "Jaeger is DEPRECATED.")
+  else()
+    message(WARNING "Jaeger is DEPRECATED.")
+  endif()
+
   find_package(Thrift QUIET)
   if(Thrift_FOUND)
     find_package(Boost REQUIRED)

DEPRECATED.md

@@ -0,0 +1,115 @@
+# Deprecated
+
+This document lists all the items currently deprecated in opentelemetry-cpp.
+
+Deprecated items will be removed in the future.
+
+## Guidelines
+
+### Maintainer guidelines
+
+See the [deprecation-process](./docs/deprecation-process.md)
+
+## [TEMPLATE]
+
+### New Deprecation Title (Template)
+
+#### Announcement (Template)
+
+#### Motivation (Template)
+
+#### Scope (Template)
+
+#### Mitigation (Template)
+
+#### Planned removal (Template)
+
+## [Platforms]
+
+N/A
+
+## [Compilers]
+
+N/A
+
+## [Third party dependencies]
+
+### Jaeger
+
+See [Jaeger exporter](#jaeger-exporter)
+
+## [Build tools]
+
+N/A
+
+## [Build scripts]
+
+N/A
+
+## [opentelemetry-cpp API]
+
+N/A
+
+## [opentelemetry-cpp SDK]
+
+N/A
+
+## [opentelemetry-cpp Exporter]
+
+### Jaeger exporter
+
+#### Announcement (Jaeger)
+
+* Version: TO-BE-RELEASED-VERSION
+* Date: TO-BE-RELEASED-DATE
+* PR: [DEPRECATION] Deprecate the Jaeger exporter
+  [#9999](https://github.com/open-telemetry/opentelemetry-cpp/pull/9999)
+
+#### Motivation (Jaeger)
+
+The Jaeger client libraries are deprecated, as announced
+[here](https://www.jaegertracing.io/docs/1.41/client-libraries/).
+
+The initial Jaeger announcement in release 1.35 reads as:
+
+"
+We plan to continue accepting pull requests and making new releases of
+Jaeger clients through the end of 2021. In January 2022 we will enter a code
+freeze period for 6 months, during which time we will no longer accept pull
+requests with new features, with the exception of security-related fixes.
+After that we will archive the client library repositories and will no
+longer accept new changes.
+"
+
+At time of writing, Jan 2023, the client libraries have been archived 6
+months ago already.
+
+#### Scope (Jaeger)
+
+The following are deprecated and planned for removal:
+
+* the API header `opentelemetry/trace/propagation/jaeger.h`, including:
+  * the C++ class `JaegerPropagator`
+* all the code located under `exporters/jaeger/`, including:
+  * the jaeger exporter C++ class (`JaegerExporter`)
+  * the related factory (`JaegerExporterFactory`)
+  * the related options (`JaegerExporterOptions`)
+* the jaeger exporter library(`opentelemetry_exporter_jaeger_trace`)
+* the jaeger build options in CMake (`WITH_JAEGER`)
+* the dependency on thrift
+
+#### Mitigation (Jaeger)
+
+Jaeger supports natively the OTLP protocol, starting with jaeger 1.35.
+
+An application instrumented with opentelemetry needs to change how the SDK
+and exporter are configured to replace the Jaeger exporter with the OTLP
+exporter (both OTLP HTTP and OTLP GRPC are supported).
+
+#### Planned removal (Jaeger)
+
+* Date: After April 1st, 2023
+
+## [Documentation]
+
+N/A

api/CMakeLists.txt

@@ -36,6 +36,11 @@ if(BUILD_TESTING)
   add_subdirectory(test)
 endif()
 
+if(WITH_NO_DEPRECATED_CODE)
+  target_compile_definitions(opentelemetry_api
+                             INTERFACE OPENTELEMETRY_NO_DEPRECATED_CODE)
+endif()
+
 if(WITH_ABSEIL)
 
   find_package(absl CONFIG REQUIRED)

api/include/opentelemetry/trace/propagation/jaeger.h

@@ -3,6 +3,10 @@
 
 #pragma once
 
+#ifdef OPENTELEMETRY_NO_DEPRECATED_CODE
+#  error "header <opentelemetry/trace/propagation/jaeger.h> is deprecated."
+#endif
+
 #include "detail/hex.h"
 #include "detail/string.h"
 #include "opentelemetry/context/propagation/text_map_propagator.h"
@@ -17,7 +21,7 @@ namespace propagation
 
 static const nostd::string_view kJaegerTraceHeader = "uber-trace-id";
 
-class JaegerPropagator : public context::propagation::TextMapPropagator
+class OPENTELEMETRY_DEPRECATED JaegerPropagator : public context::propagation::TextMapPropagator
 {
 public:
   void Inject(context::propagation::TextMapCarrier &carrier,

api/test/trace/propagation/CMakeLists.txt

@@ -1,5 +1,4 @@
-foreach(testname http_text_format_test b3_propagation_test
-                 jaeger_propagation_test)
+foreach(testname http_text_format_test b3_propagation_test)
   add_executable(${testname} "${testname}.cc")
   target_link_libraries(${testname} ${GTEST_BOTH_LIBRARIES}
                         ${CMAKE_THREAD_LIBS_INIT} opentelemetry_api)
@@ -8,3 +7,16 @@ foreach(testname http_text_format_test b3_propagation_test
     TEST_PREFIX trace.
     TEST_LIST ${testname})
 endforeach()
+
+if(NOT WITH_NO_DEPRECATED_CODE)
+  foreach(testname jaeger_propagation_test)
+
+    add_executable(${testname} "${testname}.cc")
+    target_link_libraries(${testname} ${GTEST_BOTH_LIBRARIES}
+                          ${CMAKE_THREAD_LIBS_INIT} opentelemetry_api)
+    gtest_add_tests(
+      TARGET ${testname}
+      TEST_PREFIX trace.
+      TEST_LIST ${testname})
+  endforeach()
+endif()

ci/do_ci.ps1

@@ -52,6 +52,8 @@ switch ($action) {
     cd "$BUILD_DIR"
     cmake $SRC_DIR `
       -DOTELCPP_MAINTAINER_MODE=ON `
+      -DWITH_NO_DEPRECATED_CODE=ON `
+      -DWITH_JAEGER=OFF `
       -DVCPKG_TARGET_TRIPLET=x64-windows `
       "-DCMAKE_TOOLCHAIN_FILE=$VCPKG_DIR/scripts/buildsystems/vcpkg.cmake"
     $exit = $LASTEXITCODE

ci/do_ci.sh

@@ -98,13 +98,14 @@ elif [[ "$1" == "cmake.maintainer.test" ]]; then
         -DWITH_EXAMPLES=ON \
         -DWITH_EXAMPLES_HTTP=ON \
         -DWITH_ZIPKIN=ON \
-        -DWITH_JAEGER=ON \
+        -DWITH_JAEGER=OFF \
         -DBUILD_W3CTRACECONTEXT_TEST=ON \
         -DWITH_ELASTICSEARCH=ON \
         -DWITH_LOGS_PREVIEW=ON \
         -DWITH_METRICS_EXEMPLAR_PREVIEW=ON \
         -DWITH_ASYNC_EXPORT_PREVIEW=ON \
         -DOTELCPP_MAINTAINER_MODE=ON \
+        -DWITH_NO_DEPRECATED_CODE=ON \
         "${SRC_DIR}"
   make -k
   make test