From ffc0d60a1d431431aa260fd0489e08ec97275fbb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Strehovsk=C3=BD?=
 <MichalStrehovsky@users.noreply.github.com>
Date: Tue, 3 Jun 2025 13:50:00 +0200
Subject: [PATCH 1/3] Add a note describing feature switches as last resort
 option

---
 .../FeatureSwitchDefinitionAttribute.xml              | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
index d59eeec740d..7ccf0cf26e5 100644
--- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
+++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
@@ -32,8 +32,15 @@
     </summary>
     <remarks>
       <para>
-        IL rewriters and compilers can use this attribute to substitute the return value
-        of the specified property with the value of the feature switch.</para>
+          <format type="text/markdown"><![CDATA[
+IL rewriters and compilers can use this attribute to substitute the return value of the specified property with the value of the feature switch.
+
+The value of the feature switch can only be specified at the application level and affects the entire application. It is possible to get into situations where one library that is part of the application requires the feature switch to be turned on, but has no way to communicate this to the application author.
+
+Feature switches complicate unit testing and code sharing since different application configurations may have different values of the feature switch and it's difficult to ensure all code paths work as expected.
+
+It is therefore preferable to structure APIs in a way that trimming can happen naturally without any feature switches. The use of feature switches should be reserved for situations where trimming needs to happen, but it's not feasible to change the APIs to allow trimming naturally.
+ ]]></format>
     </remarks>
     <example>
       <format type="text/markdown"><![CDATA[

From 431f9284f5571e58ace666ba34faf50e79d69226 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Strehovsk=C3=BD?=
 <MichalStrehovsky@users.noreply.github.com>
Date: Tue, 3 Jun 2025 13:53:17 +0200
Subject: [PATCH 2/3] Update FeatureSwitchDefinitionAttribute.xml

---
 .../FeatureSwitchDefinitionAttribute.xml                       | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
index 7ccf0cf26e5..2557294c5ca 100644
--- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
+++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
@@ -31,8 +31,7 @@
         corresponds to the feature switch specified by name.</para>
     </summary>
     <remarks>
-      <para>
-          <format type="text/markdown"><![CDATA[
+      <format type="text/markdown"><![CDATA[
 IL rewriters and compilers can use this attribute to substitute the return value of the specified property with the value of the feature switch.
 
 The value of the feature switch can only be specified at the application level and affects the entire application. It is possible to get into situations where one library that is part of the application requires the feature switch to be turned on, but has no way to communicate this to the application author.

From cbd5fce295cbe8d56b70dc1dfded1202ccd97eb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Strehovsk=C3=BD?=
 <MichalStrehovsky@users.noreply.github.com>
Date: Thu, 5 Jun 2025 13:00:49 -0700
Subject: [PATCH 3/3] Update
 xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
---
 .../FeatureSwitchDefinitionAttribute.xml                        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
index 2557294c5ca..a9d2a23866d 100644
--- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
+++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
@@ -36,7 +36,7 @@ IL rewriters and compilers can use this attribute to substitute the return value
 
 The value of the feature switch can only be specified at the application level and affects the entire application. It is possible to get into situations where one library that is part of the application requires the feature switch to be turned on, but has no way to communicate this to the application author.
 
-Feature switches complicate unit testing and code sharing since different application configurations may have different values of the feature switch and it's difficult to ensure all code paths work as expected.
+Feature switches complicate unit testing and code sharing since different application configurations might have different values of the feature switch, and it's difficult to ensure all code paths work as expected.
 
 It is therefore preferable to structure APIs in a way that trimming can happen naturally without any feature switches. The use of feature switches should be reserved for situations where trimming needs to happen, but it's not feasible to change the APIs to allow trimming naturally.
  ]]></format>