Add comments to package dependency to clarify the direction (#4550)

open-telemetry · Jun 10, 2023 · 3274c43 · 3274c43
1 parent d57e6f8
commit 3274c43
Showing 1 changed file with 18 additions and 0 deletions.
diff --git 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>