From 3274c43bc1031e5b25cfa7a146d428b91abc5032 Mon Sep 17 00:00:00 2001
From: Reiley Yang <reyang@microsoft.com>
Date: Fri, 9 Jun 2023 17:08:59 -0700
Subject: [PATCH] Add comments to package dependency to clarify the direction
 (#4550)

---
 Directory.Packages.props | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index f9e13e73ee4..155842462b2 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -24,10 +24,28 @@
     <PackageVersion Include="MinVer" Version="[4.2.0,5.0)" />
     <PackageVersion Include="OpenTracing" Version="[0.12.1,0.13)" />
     <PackageVersion Include="StyleCop.Analyzers" Version="[1.2.0-beta.435,2.0)" />
+
+    <!--
+        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 adding Meter/Instrument level attributes support, .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. -->
     <PackageVersion Include="System.Reflection.Emit.Lightweight" Version="4.7.0" />
+
+    <!-- A conservative version of System.Text.Encodings.Web must be used here since there is no backward compatibility guarantee during major version bumps. -->
     <PackageVersion Include="System.Text.Encodings.Web" Version="4.7.2" />
+
+    <!-- A conservative version of System.Text.Json must be used here since there is no backward compatibility guarantee during major version bumps. -->
     <PackageVersion Include="System.Text.Json" Version="4.7.2" />
+
+    <!-- A conservative version of System.Threading.Tasks.Extensions must be used here since there is no backward compatibility guarantee during major version bumps. -->
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.5.4" />
   </ItemGroup>