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)