Took care of review comments for documentation and added a few more

scenarios to the attributes and accompanying tests.

Author: praries880

Diff for: CONTRIBUTING.md

@@ -117,7 +117,7 @@ For the Storage data plane project, this change log is located at `src\Storage\C
 
 #### Breaking Changes
 
-Breaking changes should **not** be introduced into the repository without giving customers at least six months notice. For a description of breaking changes in Azure PowerShell, see [here](documentation/breaking-changes/breaking-changes-definition.md).
+Breaking changes should **not** be introduced into the repository without giving customers at least six months notice. For a description of breaking changes in Azure PowerShell and how to declare them in the code using the [various breaking change attributes](documentation/breaking-changes/breaking-changes-attribute-help.md), see [here](documentation/breaking-changes/breaking-changes-definition.md).
 
 Whenever a service team announces a breaking change, they must add it to the `upcoming-breaking-changes.md` file in their respective service folder. When the service team is ready to release the module with the breaking change, they must move the corresponding information from `upcoming-breaking-changes.md` into the `current-breaking-changes.md` file located in their service folder.
 

Diff for: documentation/breaking-changes/breaking-changes-attribute-help.md

@@ -1,6 +1,6 @@
 # Breaking Changes Attribute Help
 
-Below are descriptionsof the various types of Breaking Change Attributes (custom attributes) that can be used to decorate the cmdlet or its paramters to call out various [types of deprecations](https://github.com/praries880/azure-powershell/blob/breakingchangeattribute/documentation/breaking-changes/breaking-changes-definition.md).
+Below is description of the various types of Breaking Change Attributes (custom attributes) that can be used to decorate the cmdlet or its paramters to call out various [types of breaking changes](https://github.com/praries880/azure-powershell/blob/breakingchangeattribute/documentation/breaking-changes/breaking-changes-definition.md).
 
 ## The different types of attributes
 
@@ -41,6 +41,24 @@ NOTE :
 - The only time you will see the output (at runtime) of an attribute applied to a parameter (property or field) is if the parameter is actually invoked on the cmdline. The breaking change attributes to all parameters that are not invoked are ignored.
 
 ### Examples (with GenericBreakingChangeAttribute)
+#### With a simple message
+```cs
+    [GenericBreakingChange("Message 1")]
+    [Cmdlet(VerbsCommon.Get, "SomeObject0"), OutputType(typeof(Foo))]
+    class GetSomeObject0 : AzureRMCmdlet
+    {
+
+    }
+```
+
+##### Effects at runtime:
+```
+Get-SomeObject0 <parms here>
+...
+Breaking changes in the cmdlet : Get-SomeObject0
+ - Message 1
+```
+
 #### With "GenericBreakingChange"
 ```cs
     [GenericBreakingChange("Message 1", "5.0.0.0")]
@@ -101,7 +119,7 @@ Cmdlet invocation changes :
 
 #### With ChangeDescription property and multiple attributes in the cmdlet
 ```cs
-    [GenericBreakingChange("Message5"]
+    [GenericBreakingChange("Message5")]
     [Cmdlet(VerbsCommon.Get, "SomeObjectD"), OutputType(typeof(Foo))]
     class GetSomeObjectD : AzureRMCmdlet
         //This is just as an example, to call out a param change we would not use the generic attribute. Use "CmdletParameterBreakingChangeMarker" instead
@@ -139,7 +157,7 @@ This attribute marks a cmdlet for deprecation.
 #### Constructor Arguments
 None, other than the two inherited from GenericBreakingChangeAttribute
 
-#### When there is a replacement cmdlet for the one that is being deprecated :
+#### When there is a replacement cmdlet
 ```cs
 [CmdletDeprecation(ReplacementCmdletName = "Get-SomeObjectC")]
 [Cmdlet(VerbsCommon.Get, "SomeObjectA"), OutputType(typeof(Foo))]
@@ -197,6 +215,26 @@ Note :
 - deprecatedCmdletOutputTypeName : String, represents the type of the existing output type,
 - The two inherited from GenericBreakingChangeAttribute
 
+#### The output return type is being dropped
+```cs
+[CmdletOutputBreakingChange(typeof(Foo))]
+[Cmdlet(VerbsCommon.Get, "SomeObjectA"), OutputType(typeof(Foo))]
+public class GetSomeObjectA : AzureRMCmdlet
+{
+    protected override void BeginProcessing()
+    {
+        // cmdlet logic
+    }
+}
+```
+##### Effect at runtime
+```
+Get-SomeObjectA <parms here>
+...
+Breaking changes in the cmdlet : Get-SomeObjectA
+ - The output type 'Foo' is being deprecated without a replacement.
+```
+
 #### The output return type is changing
 ```cs
 [CmdletOutputBreakingChange(typeof(List<Foo>), ReplacementCmdletOutputTypeName = "Dictionary<String, Foo>")]
@@ -305,6 +343,31 @@ NOTE :
 - nameOfParameterChanging : String, represents the name of the existing parameter,
 - The two inherited from GenericBreakingChangeAttribute
 
+#### Generic change in a parameter
+```cs
+[Cmdlet(VerbsCommon.Get, "SomeObjectA0"), OutputType(typeof(Foo))]
+public class GetSomeObjectA0 : AzureRMCmdlet
+{
+        public const String ChangeDesc = "Change description Foo bar";
+        [CmdletParameterBreakingChange("Param1", ChangeDescription = ChangeDesc)]
+        [Parameter(Mandatory = false)]
+        public String Param1;
+    protected override void BeginProcessing()
+    {
+        // cmdlet logic
+    }
+}
+```
+
+##### Effect at runtime
+```
+Get-SomeObjectA0 -Param1=...
+...
+Breaking changes in the cmdlet : Get-SomeObjectA0
+ - The parameter 'Param1' is changing
+    Change description : Change description Foo bar
+```
+
 #### A Parameter is being deprecated
 ```cs
 [Cmdlet(VerbsCommon.Get, "SomeObjectA"), OutputType(typeof(Foo))]
@@ -330,6 +393,30 @@ Breaking changes in the cmdlet : Get-SomeObjectA
     Change description : Parameter is being deprecated without being replaced
 ```
 
+#### A Parameter is changing its type
+```cs
+[Cmdlet(VerbsCommon.Get, "SomeObjectA1"), OutputType(typeof(Foo))]
+public class GetSomeObjectA1 : AzureRMCmdlet
+{
+        [CmdletParameterBreakingChange("Param1", OldParameterType = typeof(String), NewParameterTypeName="FooBar")]
+        [Parameter(Mandatory = false)]
+        public String Param1;
+    protected override void BeginProcessing()
+    {
+        // cmdlet logic
+    }
+}
+```
+
+##### Effect at runtime
+```
+Get-SomeObjectA1 -Param1=...
+...
+Breaking changes in the cmdlet : Get-SomeObjectA1
+ - The parameter 'Param1' is changing
+    The type of the parameter is changing from 'String' to 'FooBar'.
+```
+
 #### A Parameter is being replaced
 ```cs
 [Cmdlet(VerbsCommon.Get, "SomeObjectB"), OutputType(typeof(Foo))]

Diff for: documentation/breaking-changes/breaking-changes-definition.md

@@ -1,27 +1,61 @@
 # Breaking Change Definition
 
+This document lists the various types of breaking changes and how to call them out in your code using the [breaking change attributes](./breaking-changes-attribute-help.md).
+
 Breaking changes in cmdlets are defined as follows:
 
 ## Cmdlets
 - Removing a cmdlet
+  - Use the breaking change attribute ["CmdletDeprecationAttribute"](./breaking-changes-attribute-help.md##cmdletdeprecationattribute), more specificallly the ["cmdlet deprecation without replacement"](./breaking-changes-attribute-help.md####when-there-is-no-replacement-cmdlet) option
 - Changing a cmdlet name without an alias to the original name
+  - Use the breaking change attribute ["CmdletDeprecationAttribute"](./breaking-changes-attribute-help.md##cmdletdeprecationattribute), more specificallly the ["cmdlet deprecation with replacement"](./breaking-changes-attribute-help.md####when-there-is-a-replacement-cmdlet) option
 - Removing or changing a cmdlet alias
+  - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md###genericbreakingchangeattribute) with a [simple message](./breaking-changes-attribute-help.md####with-a-simple-message) calling out the alias that is being deprecated
 - Removing a cmdlet attribute option (`SupportShouldProcess`, `SupportsPaging`)
+  - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md###genericbreakingchangeattribute) with a [simple message](./breaking-changes-attribute-help.md####with-a-simple-message) calling out the cmdlet attribute that is being removed
 - Breaking change in `OutputType` or removal of `OutputType` attribute
+  - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletoutputbreakingchangeattribute)
+    - To call out the output type being changed use the above attribute [as described here](./breaking-changes-attribute-help.md####the-output-return-type-is-changing).
+    - To deprecate an output type use the above attribute [as described here](./breaking-changes-attribute-help.md####the-output-return-type-is-being-dropped).
 
 ## Parameters
 - Removing a parameter
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####a-parameter-is-being-deprecated) to call out a parameter being removed.
 - Changing the name of a parameter without an alias to the original parameter name
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####a-parameter-is-being-replaced) to call out a parameter name change.
 - Breaking change in parameter type
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####a-parameter-is-changing-its-type) to call out a parameter name change.
 - Adding a required parameter to an existing parametrer set (adding new parameter sets or adding additional optional parameters is not a breaking change)
+  - An existing parameter becomes mandatry :
+    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####a-parameter-is-becoming-mandatory) to call out a parameter becoming mandatory.
+  - Adding a new mandatory parameter to a parameter set:
+      - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md###genericbreakingchangeattribute) with a [custom message](./breaking-changes-attribute-help.md####with-a-simple-message) calling out the new mandatiry parameter that is going to be added to the parameter set.
 - Changing parameter order for parameter sets with ordered parameters
+    - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md###genericbreakingchangeattribute) with a [custom message](./breaking-changes-attribute-help.md####with-a-simple-message) calling out the new order in the parameter set.
 - Removing or changing a parameter alias
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change by altering the change description.
 - Removing or changing existing parameter attribute values
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change by altering the change description.
 - Making parameter validation more exclusive (_e.g.,_ removing values from a `ValidateSet`)
+  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change by altering the change description.
 
 ## Output and Parameter Types
 - Changing property names without an accompanying alias to the original name
+  - In the output type
+    - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md####a-mixed-example) to call out property name changes (do not specify the attribute property "ReplacementCmdletOutputTypeName" for this purpose).
+  - In a parameter
+    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change.
 - Removing properties
+  - In the output type
+      - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md####a-few-properties-in-the-output-type-are-being-deprecated) to call out derecated properties. 
+  - In a parameter
+      - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change.
 - Adding additional required properties
+  - In the output type
+      - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md####a-few-new-properties-are-bing-added-to-the-output-type) to call out derecated properties. 
+  - In a parameter
+      - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change.
 - Adding required parameters, changing parameter names, or parameter types for methods or constructors
+    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change.
 - Changing return types of methods
+    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md##cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md####generic-change-in-a-parameter) to call out the change.

Diff for: src/Common/Commands.Common/CustomAttributes.Test/AzureRMTestCmdletDefinitiona.cs

@@ -52,6 +52,14 @@ class AzureRMTestCmdletWithCmdletDeprecationMarkerAttributeAndDescription : Azur
         public const string Description = "CmdletA2 is being replaced by CmdletA21";
     }
 
+    [Cmdlet(VerbNameHolder.CmdletNameVerb, AzureRMTestCmdletWithCmdletWithOutputTypeDropped.CmdletName)]
+    [OutputType(typeof(string))]
+    [CmdletOutputBreakingChange(typeof(string))]
+    class AzureRMTestCmdletWithCmdletWithOutputTypeDropped : AzureRMCmdlet
+    {
+        public const string CmdletName = "CmdletB0";
+    }
+
     [Cmdlet(VerbNameHolder.CmdletNameVerb, AzureRMTestCmdletWithCmdletWithOutputTypeChange.CmdletName)]
     [OutputType(typeof(string))]
     [CmdletOutputBreakingChange(typeof(string), "5.0.0.0", ReplacementCmdletOutputTypeName ="List<string>")]
@@ -87,6 +95,16 @@ class AzureRMTestCmdletWithDeprecatedParam
         public string Param1;
     }
 
+    [Cmdlet(VerbNameHolder.CmdletNameVerb, AzureRMTestCmdletWithParamTypeChange.CmdletName)]
+    class AzureRMTestCmdletWithParamTypeChange
+    {
+        public const string CmdletName = "CmdletC1A";
+        //This deprecation marker should not have the OldWay=x New way=y printed as New way is not specified
+        [CmdletParameterBreakingChange("Param1", OldParamaterType = typeof(string), NewParameterTypeName = "List<string>")]
+        [Parameter(Mandatory = false)]
+        public string Param1;
+    }
+
     [Cmdlet(VerbNameHolder.CmdletNameVerb, AzureRMTestCmdletWithReplacedParam.CmdletName)]
     class AzureRMTestCmdletWithReplacedParam
     {

Diff for: src/Common/Commands.Common/CustomAttributes.Test/BreakingChangeAttributeTests.cs

@@ -92,6 +92,28 @@ public void TestForCmdletDeprecationAttributeWithDescription()
             Assert.False(messages[0].Contains("powershell\r\n# Old"));
         }
 
+        [Fact]
+        [Trait(Category.AcceptanceType, Category.CheckIn)]
+        public void TestForCmdletOutputTypeDropped()
+        {
+            List<GenericBreakingChangeAttribute> attribs = BreakingChangeAttributeHelper.GetAllBreakingChangeAttributesInType(typeof(AzureRMTestCmdletWithCmdletWithOutputTypeDropped), null);
+
+            Assert.Equal(1, attribs.Count);
+            Assert.False(attribs[0].ChangeInEfectByDateSet);
+            Assert.False(attribs[0].DeprecateByVersionSet);
+
+            string pat = @"(The output type ')(.*)(' is being deprecated without a replacement.)";
+            Regex reg = new Regex(pat, RegexOptions.IgnoreCase | RegexOptions.Singleline);
+            List<string> messages = BreakingChangeAttributeHelper.GetBreakingChangeMessagesForType(typeof(AzureRMTestCmdletWithCmdletWithOutputTypeDropped));
+            Assert.Equal(1, messages.Count);
+            Assert.True(reg.IsMatch(messages[0]));
+            Assert.True(messages[0].Contains(" - Cmdlet : '" + VerbNameHolder.CmdletNameVerb + "-" + AzureRMTestCmdletWithCmdletWithOutputTypeDropped.CmdletName));
+            Assert.False(messages[0].Contains("This change will take effect on '"));
+            Assert.False(messages[0].Contains("Change description : "));
+            Assert.False(messages[0].Contains("The change is expected to take effect from the version"));
+            Assert.False(messages[0].Contains("powershell\r\n# Old"));
+        }
+
         [Fact]
         [Trait(Category.AcceptanceType, Category.CheckIn)]
         public void TestForCmdletOutputTypeDeprecation()
@@ -181,6 +203,30 @@ public void TestForCmdletWithParamDeprecatedNoReplacement()
             Assert.True(messages[0].Contains("Change description : " + AzureRMTestCmdletWithDeprecatedParam.ChangeDesc));
         }
 
+        [Fact]
+        [Trait(Category.AcceptanceType, Category.CheckIn)]
+        public void TestForCmdletWithParamTypeChange()
+        {
+            List<GenericBreakingChangeAttribute> attribs = BreakingChangeAttributeHelper.GetAllBreakingChangeAttributesInType(typeof(AzureRMTestCmdletWithParamTypeChange), null);
+            Assert.Equal(1, attribs.Count);
+            Assert.False(attribs[0].ChangeInEfectByDateSet);
+            Assert.False(attribs[0].DeprecateByVersionSet);
+
+            string pat = @"(The parameter : ')(.*)(' is changing)";
+            string pat1 = @"(The type of the parameter is changing from ')(.*)(' to ')(.*)('.)";
+            Regex reg = new Regex(pat, RegexOptions.IgnoreCase | RegexOptions.Singleline);
+            Regex reg1 = new Regex(pat1, RegexOptions.IgnoreCase | RegexOptions.Singleline);
+            List<string> messages = BreakingChangeAttributeHelper.GetBreakingChangeMessagesForType(typeof(AzureRMTestCmdletWithParamTypeChange));
+            Assert.Equal(1, messages.Count);
+            Assert.True(reg.IsMatch(messages[0]));
+            Assert.True(reg1.IsMatch(messages[0]));
+            Assert.True(messages[0].Contains(" - Cmdlet : '" + VerbNameHolder.CmdletNameVerb + "-" + AzureRMTestCmdletWithParamTypeChange.CmdletName));
+            Assert.False(messages[0].Contains("This change will take effect on '"));
+            Assert.False(messages[0].Contains("The change is expected to take effect from the version"));
+            Assert.False(messages[0].Contains("powershell\r\n# Old"));
+            Assert.False(messages[0].Contains("Change description : "));
+        }
+
         [Fact]
         [Trait(Category.AcceptanceType, Category.CheckIn)]
         public void TestForCmdletWithParamDeprecatedWithReplacement()