breaking-changes-definition.md

WARNING:
This page is moved to Breaking Change Definition. DO NOT UPDATE IT HERE!

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 in cmdlets are defined as follows:

Cmdlets

• Removing a cmdlet
  • Use the breaking change attribute "CmdletDeprecationAttribute", more specifically the "cmdlet deprecation without replacement" option
• Changing a cmdlet name without an alias to the original name
  • Use the breaking change attribute "CmdletDeprecationAttribute", more specifically the "cmdlet deprecation with replacement" option
• Removing or changing a cmdlet alias
  • Use the generic breaking change attribute "GenericBreakingChangeAttribute" 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" 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"
    • To call out the output type being changed use the above attribute as described here.
    • To deprecate an output type use the above attribute as described here.

Parameters

• Removing a parameter
  • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here 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" as described here to call out a parameter name change.
• Breaking change in parameter type
  • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here to call out a parameter name change.
• Adding a required parameter to an existing parameter set (adding new parameter sets or adding additional optional parameters is not a breaking change)
  • An existing parameter becomes mandatory :
    • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here to call out a parameter becoming mandatory.
  • Adding a new mandatory parameter to a parameter set:
    • Use the generic breaking change attribute "GenericBreakingChangeAttribute" with a custom message calling out the new mandatory 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" with a custom message calling out the new order in the parameter set.
• Removing or changing a parameter alias
  • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here to call out the change by altering the change description.
• Removing or changing existing parameter attribute values
  • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here 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" as described here 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" as follows 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" as described here to call out the change.
• Removing properties
  • In the output type
    • Use the cmdlet output type breaking change attribute "CmdletOutputBreakingChangeAttribute" as follows to call out deprecated properties.
  • In a parameter
    • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here to call out the change.
• Adding additional required properties
  • In the output type
    • Use the cmdlet output type breaking change attribute "CmdletOutputBreakingChangeAttribute" as follows to call out deprecated properties.
  • In a parameter
    • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here 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" as described here to call out the change.
• Changing return types of methods
  • Use the parameter breaking change attribute "CmdletParameterBreakingChangeAttribute" as described here to call out the change.