From f849de7acec00e3420faf614eb050663ae21ac54 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 27 Sep 2022 18:00:48 -0700 Subject: [PATCH 1/6] Proposal for dropping .NET Standard --- netstandard.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 netstandard.md diff --git a/netstandard.md b/netstandard.md new file mode 100644 index 00000000000..0c62428efe1 --- /dev/null +++ b/netstandard.md @@ -0,0 +1,108 @@ +# Dropping support for .NET Standard + +## Background + +The OpenTelemetry .NET project depends heavily on APIs provided by .NET. +Specifically, the APIs provided under `System.Diagnostics.DiagnosticSource`. + +With the release of .NET 6, [it was announced](https://github.com/dotnet/announcements/issues/190) +that the .NET team will drop out-of-support frameworks for a number of packages +including `System.Diagnostics.DiagnosticSource`. This practice will continue +with the release of .NET 7. Frameworks no longer supported will include .NET +Core 3.1 and .NET 5. Refer to the [.NET download](https://dotnet.microsoft.com/download/dotnet) +page to view the end of support dates for each version of .NET. + +The core packages offered by OpenTelemetry .NET currently ship a .NET +Standard build (i.e., `netstandard2.0` and/or `netstandard2.1`). +Therefore, OpenTelemetry .NET can technically be consumed by projects targeting +out-of-support frameworks - even as far back as .NET Core 2.0. + +However, referencing the latest version of OpenTelemetry .NET by an application +targeting .NET Core 3.1 or .NET 5 will generate the following build warnings: + +> System.Diagnostics.DiagnosticSource doesn't support netcoreapp3.1. Consider updating your TargetFramework to net6.0 or later. +> System.Diagnostics.DiagnosticSource doesn't support net5.0. Consider updating your TargetFramework to net6.0 or later. + +These warnings can be suppressed by setting the +`SuppressTfmSupportBuildWarnings` MSBuild property. However, +OpenTelemetry .NET is not tested against out-of-support frameworks. Therefore +there is no guarantee that it will continue to function. + +## The plan to remove .NET Standard targets + +The plan moving forward is to align the support cycle of OpenTelemetry .NET +with the support cycle of .NET. To achieve this, OpenTelemetry .NET plans to +drop .NET Standard builds of its artifacts. OpenTelemetry packages will only +offer implementation specific target frameworks (e.g., `net462` and `net6.0`). +This will enable us to easily test and validate that OpenTelemetry .NET works +as expected for all the frameworks we target. + +At this time, the frameworks targeted will include at least `net462` and +`net6.0`, but may include others like `net7.0`, when appropriate. As target +frameworks reach end of life, we will remove those targets during a major +version release roughly aligned with the corresponding major version release +of .NET. + +Given that dropping a framework from a package is a source breaking change, we +will coordinate dropping .NET Standard targets with a major version release for +all of our stable packages. + +That said, the OpenTelemetry .NET project offers a number of packages that have +not yet had a stable release. We will be removing .NET Standard builds from the +following packages now: + +* `OpenTelemetry.Exporter.Prometheus.AspNetCore` +* `OpenTelemetry.Exporter.Prometheus.HttpListener` +* `OpenTelemetry.Exporter.ZPages` +* `OpenTelemetry.Extensions.Hosting` +* `OpenTelemetry.Instrumentation.AspNetCore` +* `OpenTelemetry.Instrumentation.GrpcNetClient` +* `OpenTelemetry.Instrumentation.Http` +* `OpenTelemetry.Instrumentation.SqlClient` +* `OpenTelemetry.Shims.OpenTracing` + +## How users will be impacted by removing .NET Standard builds + +### Sharing code between .NET Framework and .NET 6+ applications + +It has been a common practice for users to place shared code in a class library +targeting .NET Standard. For example, the following project might be used to +centralize the configuration of OpenTelemetry across both your .NET Framework +and .NET 6+ applications. + +```xml + + + netstandard2.0 + + + + + + +``` + +With the removal of .NET Standard targets from OpenTelemetry packages, this +example project must now be multi-targeted as follows: + +```xml + + + net6.0;net462 + + + + + + +``` + +### Referencing OpenTelemetry packages from Xamarin and Mono projects + +Technically, both Xamarin and Mono implement `netstandard2.0`. However, +OpenTelemetry does not currently support either despite currently offering +a `netstandard2.0` build. + +If in the future Xamarin or Mono are supported by OpenTelemetry .NET, we +will add this support via framework specific targets (i.e., `xamarin.android` +or `net6.0-android`). From c26fc97bd189a5faddd473a53be378d6ef389533 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 27 Sep 2022 18:11:08 -0700 Subject: [PATCH 2/6] Fix quote --- netstandard.md | 1 + 1 file changed, 1 insertion(+) diff --git a/netstandard.md b/netstandard.md index 0c62428efe1..153f454688e 100644 --- a/netstandard.md +++ b/netstandard.md @@ -21,6 +21,7 @@ However, referencing the latest version of OpenTelemetry .NET by an application targeting .NET Core 3.1 or .NET 5 will generate the following build warnings: > System.Diagnostics.DiagnosticSource doesn't support netcoreapp3.1. Consider updating your TargetFramework to net6.0 or later. + > System.Diagnostics.DiagnosticSource doesn't support net5.0. Consider updating your TargetFramework to net6.0 or later. These warnings can be suppressed by setting the From d56119028c1e9ab1f88577b2c93a8a92f8da5b89 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 27 Sep 2022 18:26:03 -0700 Subject: [PATCH 3/6] Add example --- netstandard.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/netstandard.md b/netstandard.md index 153f454688e..0c30c9c07ec 100644 --- a/netstandard.md +++ b/netstandard.md @@ -44,13 +44,30 @@ frameworks reach end of life, we will remove those targets during a major version release roughly aligned with the corresponding major version release of .NET. -Given that dropping a framework from a package is a source breaking change, we -will coordinate dropping .NET Standard targets with a major version release for -all of our stable packages. +For example: + +Currently the [OpenTelemetry SDK project](/blob/ee11de90a37915c68d9d44cdd283ba6047b394a3/src/OpenTelemetry/OpenTelemetry.csproj#L4) +contains the following targets: + +```xml +net6.0;netstandard2.1;netstandard2.0;net462 +``` + +When .NET 6 reaches end of life November 2024, the net6.0 and .NET Standard targets +will be removed and we will perform a major version release of the OpenTelemetry +.NET SDK. Presumably, at that time .NET 8 will have been released, and the +the project file may look like: + +```xml +net8.0;net462 +``` + +Since dropping a framework from a package is a source breaking change, the above +example describes our process for all of our stable packages. That said, the OpenTelemetry .NET project offers a number of packages that have not yet had a stable release. We will be removing .NET Standard builds from the -following packages now: +following packages ing the next minor release: * `OpenTelemetry.Exporter.Prometheus.AspNetCore` * `OpenTelemetry.Exporter.Prometheus.HttpListener` From 366e907613fe89141ab86f7fd0650ed2ebf02aef Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 27 Sep 2022 18:31:54 -0700 Subject: [PATCH 4/6] Minor fixes --- netstandard.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/netstandard.md b/netstandard.md index 0c30c9c07ec..736cb33207a 100644 --- a/netstandard.md +++ b/netstandard.md @@ -18,7 +18,8 @@ Therefore, OpenTelemetry .NET can technically be consumed by projects targeting out-of-support frameworks - even as far back as .NET Core 2.0. However, referencing the latest version of OpenTelemetry .NET by an application -targeting .NET Core 3.1 or .NET 5 will generate the following build warnings: +targeting .NET Core 3.1 or .NET 5, for example, will generate the following +build warnings: > System.Diagnostics.DiagnosticSource doesn't support netcoreapp3.1. Consider updating your TargetFramework to net6.0 or later. @@ -53,10 +54,10 @@ contains the following targets: net6.0;netstandard2.1;netstandard2.0;net462 ``` -When .NET 6 reaches end of life November 2024, the net6.0 and .NET Standard targets +When .NET 6 reaches end of life November 2024, the `net6.0` and .NET Standard targets will be removed and we will perform a major version release of the OpenTelemetry .NET SDK. Presumably, at that time .NET 8 will have been released, and the -the project file may look like: +the project file may look like this: ```xml net8.0;net462 @@ -67,7 +68,7 @@ example describes our process for all of our stable packages. That said, the OpenTelemetry .NET project offers a number of packages that have not yet had a stable release. We will be removing .NET Standard builds from the -following packages ing the next minor release: +following packages in the next minor release: * `OpenTelemetry.Exporter.Prometheus.AspNetCore` * `OpenTelemetry.Exporter.Prometheus.HttpListener` From 92768bc743dcfd55c4a6d8824dfea054ee9e9975 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 28 Sep 2022 09:04:04 -0700 Subject: [PATCH 5/6] fix link --- netstandard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netstandard.md b/netstandard.md index 736cb33207a..5c03657ca4f 100644 --- a/netstandard.md +++ b/netstandard.md @@ -47,7 +47,7 @@ of .NET. For example: -Currently the [OpenTelemetry SDK project](/blob/ee11de90a37915c68d9d44cdd283ba6047b394a3/src/OpenTelemetry/OpenTelemetry.csproj#L4) +Currently the [OpenTelemetry SDK project](https://github.com/open-telemetry/opentelemetry-dotnet/blob/ee11de90a37915c68d9d44cdd283ba6047b394a3/src/OpenTelemetry/OpenTelemetry.csproj#L4) contains the following targets: ```xml From aad51604f32e0a36970fa11c29f43e50c1faf87d Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 28 Sep 2022 09:35:12 -0700 Subject: [PATCH 6/6] Update netstandard.md Co-authored-by: Cijo Thomas --- netstandard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netstandard.md b/netstandard.md index 5c03657ca4f..27532cee7e9 100644 --- a/netstandard.md +++ b/netstandard.md @@ -2,7 +2,7 @@ ## Background -The OpenTelemetry .NET project depends heavily on APIs provided by .NET. +The OpenTelemetry .NET project depends heavily on APIs provided by [.NET Runtime](https://github.com/dotnet/runtime). Specifically, the APIs provided under `System.Diagnostics.DiagnosticSource`. With the release of .NET 6, [it was announced](https://github.com/dotnet/announcements/issues/190)