From 26727bfb2ff79bb321e804d0bf64587c768290d7 Mon Sep 17 00:00:00 2001
From: Reiley Yang <reyang@microsoft.com>
Date: Wed, 7 Jun 2023 14:46:20 -0700
Subject: [PATCH] add more context

---
 Directory.Packages.props | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index d74fbdbf999..6d72ca9e3c0 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -25,7 +25,15 @@
     <PackageVersion Include="OpenTracing" Version="[0.12.1,0.13)" />
     <PackageVersion Include="StyleCop.Analyzers" Version="[1.2.0-beta.435,2.0)" />
 
-    <!-- The latest stable version of System.Diagnostics.DiagnosticSource should be used here since the .NET runtime team provides extra backward compatibility guarantee even during major version bumps. -->
+    <!--
+        Typically, the latest stable version of System.Diagnostics.DiagnosticSource should be used here because:
+        1) Each major version bump will have some new OpenTelemetry API capabilities (e.g. .NET 6 introduced Meter
+           API, .NET 7 added UpDownCounter, .NET 8 is improving dependency injection support for Meter/Instrument,
+           .NET 9 might add Advice/Hint API) that the OpenTelemetry components rely on.
+        2) Each minor version bump is normally security hotfixes or critical bug fixes.
+        3) The .NET runtime team provides extra backward compatibility guarantee to System.Diagnostics.DiagnosticSource
+           even during major version bumps, so compatibility is not a concern here.
+    -->
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="7.0.0" />
 
     <!-- A conservative version of System.Reflection.Emit.Lightweight must be used here since there is no backward compatibility guarantee during major version bumps. -->