[MAINTAINER DOC] Define and document a deprecation process

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,113 @@
+# 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:
+
+* 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,10 @@ 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()